Troubleshooting and diagnostics
A symptom-based guide for startup, calibration, astrometry, stacking, catalogue access and comet photometry in the current KOPR live build.
Source-verified Corrective actions combine the audited KOPR/WSL baseline with the supplied Scientific/Compact implementation documentation dated 24 July 2026.
Preserve the evidence. Before retrying a failed reduction, keep the original images, the exact terminal output, the WStack log, generated CSV/JSON reports and any partially created FITS products. Do not edit the original science data to make an error disappear.
First response to any failure
- Read the final error and the lines immediately above it. WStack reports the active stage, current file and often the exact rejection reason.
- Identify the first failing stage. A later photometry error may be caused by an earlier metadata, calibration, WCS or pair-contract problem.
- Use the generated reports. Master creation writes frame and group CSV reports, and WStack stores local state, manifests and QC diagnostics.
- Retry only after correcting the cause. Repeating the same operation with the same inputs normally reproduces the same result and can obscure which files belong to which attempt.
Useful general references: installation, configuration, WStack workflow, CCD photometry and data/FITS reference.
Startup and installation
| Symptom | Likely cause | Corrective action |
|---|---|---|
ModuleNotFoundError | The KOPR virtual environment is not active or a required package is absent. | Activate .venv, install docs/files/kopr-python-requirements.txt, then run check-kopr-install.py. |
| Linux Qt cannot connect to a display | KOPR is being launched from a text-only session or SSH session without a graphical display. | Run it in a graphical desktop or configure display forwarding. Native Windows KOPR does not require WSLg. |
| Relative files or directories are not found | KOPR was started from a different current working directory. | Change into the directory containing kopr.py before running python kopr.py. |
| Configuration incomplete | Observer data or one of the required equipment lists is empty. | Open , save the missing observer/location/telescope/camera/eyepiece entries, close the dialog with OK, then select the active items from the Configuration menu. |
KOPR cannot create config-files/, comet-data/ or obs-data/ | The application directory is read-only or owned by another user. | Move KOPR to a user-writable directory. Do not run the GUI as administrator/root merely to bypass permissions. |
| Windows KOPR starts, but astrometry cannot start WSL | WSL is missing, outdated, not initialized or blocked by disabled virtualization. | Run wsl --status and wsl --list --verbose; update WSL and enable the required Windows/BIOS virtualization features. |
data/de440s.bsp is missing | This is normal in R22. Use the first-start progress dialog. Cancel continues with the legacy ephemeris fallback; Retry starts another verified attempt without restarting KOPR. A command-line attempt is available through python de440s_fetch.py. | |
| The DE440s download fails or is cancelled | KOPR remains usable in legacy ephemeris mode. Correct the network, permission or free-space problem and press Retry. Only a verified file is installed atomically; temporary .part data are cleaned up. | |
| A DE440s kernel already exists elsewhere | Set KOPR_DE440S to the verified kernel path before starting KOPR. |
Working directory and input files
| Message or display | Meaning | Action |
|---|---|---|
(no input FITS frames) | The FITS-only working index is empty. Pending DSLR RAW may have failed materialization or the directory contains no usable FITS. | Review the extraction result or DSLR RAW extraction unavailable message, install rawpy/LibRaw when required, and reopen the directory. See DSLR RAW materialization. |
(astrometry has not produced any WCS files yet) | No solved products are registered for the current directory. | Complete calibration, enable the intended CALIB frames, then run Astrometry. |
(no stack files) | No final WStack products were found. | Run a star/comet stack, or open the directory that contains the final ST_.../CO_... files. |
| Cannot open directory | The path disappeared, is inaccessible, or cannot be scanned. | Verify the mount, path and read permissions. Re-open the directory rather than editing pipeline_state.json manually. |
| The extraction progress opens immediately after selecting a DSLR directory | This is the intended R74 behavior: pending or stale representations are materialized automatically. | Allow the batch to finish or use its cooperative Cancel button. There is no separate extraction decision dialog. |
| DSLR RAW extraction unavailable | rawpy/LibRaw is not available while pending or stale RAW sources require decoding. | Install rawpy and restart KOPR. Existing FITS may still open; if no usable FITS exists, the previous session is preserved. |
| Extraction Cancel did not stop the current file immediately | Cancellation is cooperative between RAW files. | Allow the active decoder to finish safely. Completed FITS remains; remaining RAW sources are processed automatically next time the directory is opened. |
| A TG FITS target is skipped as conflicting | The deterministic target is foreign, unreadable or represents a second genuine direct RAW materialization. R81 no longer treats CALIB/WCS/CO/ST derivatives with historical RAWFILE/RAWEXT as competing direct representations. | Check RAWREP and the product-identifying cards. Preserve or move a genuinely foreign/direct conflict; do not delete valid derived products merely because they record RAW ancestry. |
| Reopening a DSLR directory reports several representations of one RAW | On an older build, derived products may have inherited RAWFILE/RAWEXT and been mistaken for direct TG FITS. | Use R81 or newer. Direct representations use RAWREP=T; derivatives are recognized by RAWREP=F, product cards or legacy names. Two genuine direct representations still require manual resolution. |
| A physical CR2/NEF/etc. is not visible on the Raw page | This is the intended R74 FITS-only session policy. | Use the corresponding verified _TG.fits. The Raw page name denotes the workflow stage, not the physical file format. |
| Unsupported stack | The FITS file lacks a recognized final STACKTYP, is damaged, or is an ordinary exposure that only happens to contain a stack-like keyword. | Inspect the primary header. A measurement product must identify COMET/COMET-AUTO/STARS and must satisfy the documented stack contract. |
input FITS contains no 2D image | No two-dimensional image HDU could be selected. | Check the file with Astropy or another FITS viewer. Export a genuine image FITS; do not rename a table or empty container to .fits. |
Master darks and master flats
The completion dialog includes accepted/rejected counts, primary reasons and a detailed section. The authoritative per-frame records are written to masterdark_QC_report.csv or masterflat_QC_report.csv; group reports explain why a compatible group was not created.
| Reported reason | Interpretation | Action |
|---|---|---|
missing EXPTIME | The calibration frame cannot be grouped or safely matched. | Correct the acquisition/export metadata. Do not invent an exposure unless it is independently known. |
missing FILTER or missing BINNING on a flat | Flat compatibility is ambiguous. | Add the correct metadata during a controlled export, or use source files that preserve it. |
too many NaN/Inf values | A substantial part of the frame is not finite. | Inspect the image and the producing software. Replace corrupted frames. |
excessive saturated-pixel fraction | The measured fraction exceeds the hard limit displayed by KOPR. | Inspect actual pixel values and the detector saturation metadata (SATURATE, SATLEVEL, MAXADU, ADC-MAX). Retake overexposed flats/darks; do not raise the hard limit to accept invalid data. |
excessive hot-pixel fraction | A dark-like exposure has an implausibly large hot-pixel population. | Check exposure type, temperature, gain/offset and file scaling. A LIGHT or stretched image may have been selected as a dark. |
excessive bright-local-outlier fraction | A flat contains too many stellar or local bright structures. | Use uniformly illuminated flats and reject frames contaminated by stars, moving shadows or reflections. |
median outside the allowed ADC range | The flat is too dark or too close to the detector limit for reliable normalization. | Retake flats at a suitable exposure. Confirm that the header detector limit matches the stored data scale. |
whole-frame outlier | The frame median/noise or illumination pattern is inconsistent with its group. | Inspect the frame and acquisition sequence. Keep it rejected unless there is a documented reason the group itself is wrong. |
loading error | The file could not be decoded as a supported image. | Open that specific file independently and compare it with accepted files from the same camera. |
| No master ... group is eligible | After compatibility grouping and QC, no group has enough usable frames or required metadata. | Read both CSV reports and the detailed dialog. Correct the dominant reason rather than combining incompatible groups manually. |
| No matching dark-flat/bias for a flat | The flat correction stage cannot select one unique compatible offset master. | Create a compatible dark-flat, or a bias where the workflow permits it. Resolve ties and metadata mismatches in the master library. |
the flat cannot be normalized after correction | The corrected flat has no stable positive median. | Inspect the selected offset master and flat exposure. This is not repaired by synthetic normalization. |
Unexpected master-flat correction
Stop before accepting the build and review the R75 correction guard. Confirm that the proposed bias, dark-flat or dark correction belongs to the flat group. The guard is intended to prevent a correction from being applied silently.
LIGHT calibration
| Message | Cause | Action |
|---|---|---|
frame has no valid pre-calibration QC record | The input did not pass or retain the raw-LIGHT QC state expected by the calibration run. | Return to Raw, rescan and run/select the intended QC inputs. |
no compatible master dark or master flat found | The library has no complete compatible pair. | Compare exposure, temperature, dimensions, binning, instrument, gain, offset, read mode and filter. Build the missing compatible master. |
only a master flat was found / only a master dark was found | The current workflow forbids one-sided calibration. | Provide both compatible masters. Do not treat a partial calibration as equivalent. |
CALTYPE=... but DARK is required | A BIAS or DARKFLAT was selected where LIGHT calibration requires a master DARK. | Correct the master library and metadata. |
| Master exposure or temperature does not match LIGHT | The difference exceeds the configured tolerance. | Create a closer master group or correct erroneous header metadata. KOPR does not silently scale an incompatible dark. |
| Master dimensions differ from LIGHT | ROI, camera mode or binning differs. | Use masters created with the same detector geometry. |
| Master flat has invalid/zero pixels above the limit | Division by the flat would corrupt too much of the output. | Rebuild the flat from better source frames and verify its offset correction. |
Review processing_manifest.json after calibration. It records source-to-calibrated paths and the selected master files.
Scientific and Compact output
| Symptom | Meaning and action |
|---|---|
| Compact was selected but one file is Scientific | This is expected when the required QSTEP exceeds 0.25 × sigma_local. Inspect REQMODE, QSAFE, QFALLBK, QNOISE and QMAX. KOPR deliberately avoids clipping or unsafe coarse quantization. |
| The whole FITS is not 50% smaller | Only the primary science payload changes from four to two bytes per pixel. Coverage, clipping, saturation, provenance and tracking extensions remain. |
| Peak RAM is not halved in Compact mode | Expected. Calibration, reprojection, stacking and photometry still use floating-point working arrays. |
| A Compact file appears as floating point after reading | Expected. Astropy applies BSCALE/BZERO/BLANK and returns physical values. |
| Header says Compact but scaling cards are inconsistent | Treat this as a damaged or non-conforming FITS. Preserve the file, record the science HDU and scaling cards, and run the validation tool before measurement. |
Use validate_scientific_compact.py --compare scientific.fits compact.fits --json pair-validation.json to quantify pixel and optional aperture differences. See Scientific and Compact FITS output.
Astrometry and index installation
| Message or symptom | Meaning | Action |
|---|---|---|
solve-field was not found on PATH (Linux/non-Windows) | The native Astrometry.net command is not installed or is outside PATH. | Install the system package and verify command -v solve-field in the same environment used to start KOPR. |
KOPR found neither native solve-field nor wsl.exe | Native Windows has no usable solver backend. | Install WSL 2 and Astrometry.net in Ubuntu, or provide a native Windows solver on PATH. |
WSL is installed, but solve-field was not found in the selected distribution | The default/selected WSL distribution does not contain Astrometry.net. | Run sudo apt install astrometry.net in that distribution. If another distribution contains it, set KOPR_WSL_DISTRIBUTION to its exact name. |
| WSL could not translate the Windows path | wslpath cannot map the KOPR/data/work/index location. | Use an ordinary local C: or D: path. Avoid an unavailable network/UNC path and verify the drive is visible as /mnt/c, /mnt/d, etc. |
| No index download follows a solver error | Solver preflight now intentionally runs before index installation. | Repair the solver backend first. KOPR will check/download indexes only after preflight succeeds. |
No 42xx indexes were found | The local 4200-series index directory is empty or incomplete. | After solver preflight succeeds, use KOPR's downloader or install the required files into astrometry-index/4200/. |
The index directory contains no FITS indexes | A configured index path exists but contains no usable index FITS files. | Correct the WStack path or complete the download. Remove stale .part files only after confirming no download is active. |
| Index download lists missing series | One or more requested 4206–4214 series were not completed. | Retry with stable network access and enough disk space; partial files can resume. |
no complete astrometry seed ... missing RA/DEC/scale_low/scale_high | The offline automatic chain and any explicit manual override did not produce complete position and scale constraints. | Check FITS WCS/pointing, comet designation and active location/camera/telescope. To override automatic values, edit both RA/DEC or both scale limits in the dialog opened by Astrometry; clear both scale fields to return to automatic scale. |
| Unexpected automatic offline RA/DEC | The value comes from the current automatic chain: FITS WCS/pointing first, otherwise the internal comet ephemeris. Per-group manual coordinates are stored in pipeline_state.json, not in general QSettings. | Inspect the FITS header and session state before assuming stale preferences. For a bit-for-bit ephemeris audit, also record whether the runtime used de440s.bsp or the legacy fallback. |
| Internal ephemeris has no local orbital elements | The comet designation is not present in the local element database. | Update the orbital elements or add validated custom elements. Check designation syntax. |
solve-field failed (return=...) | The external solver started but exited unsuccessfully. | Read the included tail of the solver log. Typical causes are wrong scale/position seed, missing indexes, too few detectable stars, a non-linear/stretched image or an invalid FITS. |
| WCS is far from the supplied seed or fails inverse validation | The solution is syntactically valid but geometrically inconsistent or on the wrong field. | Correct the seed, scale and image metadata. Do not accept the file merely because WCS cards exist. |
solve-field did not create a readable AXY source list | The WCS may be usable, but post-solve star-quality diagnostics could not be measured. | Inspect the solver log and AXY output. Stacking still performs its own WCS preflight. |
| Blind online upload times out or reports no job ID | nova.astrometry.net did not accept or complete the blind upload/job within the polling interval. | Retry later and verify the API key and network. R48 does not send centre, radius, scale, parity or downsampling constraints; the returned centre/scale is used only after a successful job. |
Online log repeatedly shows queued or solving | The server job is still active. R48 reports periodic status heartbeats and intentionally does not request calibration yet. | Wait for status=success or a terminal failure. Repeated no calibration data available polling is not expected. |
| Online job succeeds but calibration cannot be read | The server reported success but did not return a usable calibration payload. | Preserve the job ID and log, retry later, or continue with offline Astrometry. Do not restore local upload constraints as a workaround. |
SKIPPED_ANCHOR_FAILED | A required group anchor exhausted the three-stage solve strategy. With the recommended policy, the remaining group members were intentionally not retried under the same conditions. | Open the anchor's Attempt 1–3 logs. Check seeds, scale/radius, index availability and the robust-copy diagnostics. Rerun after correction, or select Continue with independent seeds only for a heterogeneous series. |
[FAILED] followed by several [SKIPPED] lines | This is the group anchor failure guard, not loss of files or settings. | Use the group summary to identify the failed anchor. The calibrated inputs and group configuration remain available for another run. |
[INDEX] available=... lists 4200 but not 4100 | The optional Tycho-2 4100 family is absent. | Continue with 4200. Install 4107–4112 only when wider-field work needs the optional family; the automatic downloader remains 4206–4214. |
| Robust-copy attempt reports many replaced impulses | KOPR found isolated positive/negative extremes and replaced them only in a temporary solver input. | Compare the count across frames and inspect the full attempt log. Multi-pixel stellar profiles should remain; the calibrated source FITS is not edited. |
Direct Windows/WSL checks
wsl --status
wsl --list --verbose
wsl.exe -d Ubuntu -- sh -lc "command -v solve-field"
wsl.exe -d Ubuntu -- sh -lc "solve-field --help >/dev/null && echo SOLVER_OK"Replace Ubuntu with the exact selected distribution name. After installing Astrometry.net or changing KOPR_WSL_DISTRIBUTION, close and restart KOPR so the cached backend is resolved again.
Scale or ephemeris differs from another program
Record the active source in the shared scale priority: solved WCS/online calibration, manual override, FITS metadata or active optics with validated binning. For comet positions, also record whether DE440s down-leg light-time or the fallback path was used. Guide, Tycho and Horizons comparisons are diagnostic; do not apply a universal arcsecond threshold to every comet and epoch.
Relative WCS quality control
After solving and again before stacking, KOPR compares star positions between frames. A valid-looking FITS WCS can still be rejected when relative matching is inaccurate.
| Observation | Interpretation and action |
|---|---|
relative WCS rejected | Read the reason, matched-star count/fraction and residual diagnostics. Inspect the rejected frame for tracking, clouds, incorrect WCS, duplicated fields or a different camera geometry. |
| Many frames rejected against one reference | The reference itself may be poor. Review FWHM/elongation and choose a representative, well-solved frame before rerunning. |
| More than 25% rejected | KOPR requests explicit confirmation. Continue only when the remaining set is scientifically adequate and the rejection reasons are understood. |
| Rejected solved files disappear from Astro | This is expected: KOPR removes inaccurate WCS products where possible and clears stale CALIB→WCS state links. |
| Batch validation skipped after cancellation | Already completed WCS products remain, but are not trusted automatically; stack preflight will validate them again. |
Stacking
| Symptom | Cause | Action |
|---|---|---|
| No enabled WCS inputs | Astro selections are off, missing or rejected. | Enable only valid solved LIGHT frames. Re-run the Astro page scan after correcting state. |
| Science stack expects LIGHT/OBJECT/SCIENCE but another type is detected | A calibration master or non-science file entered the group. | Remove it from the enabled Astro set and correct IMAGETYP. |
| Unknown stacking mode | The requested operation is outside the supported star/comet/pair modes. | Use the GUI action and a supported combination method rather than editing state JSON. |
| Dimensions changed during processing | An input file was replaced or altered after preflight. | Restore an immutable input set, reopen the directory and rerun. |
| Stacking cancelled | The user cancelled or did not confirm continuation after WCS rejection. | Wait for the worker to finish cleanup. Treat partial temporary files as incomplete. |
| Unexpected crop or NaN borders | WCS overlap does not cover the entire reference geometry. | Inspect NCONTRIB/NVALID, selected crop mode and rejected frames. NaN outside required coverage is intentional. |
| Sigma-clipping threshold error | The requested sigma is below 3.0 or rejection-fraction settings are outside the accepted range. | Use the GUI-supported values. The maximum-rejected-fraction metric is diagnostic, not permission to discard all samples in a pixel. |
Stack Parameters stops before processing
R75 runs one explicit preflight before stack execution. Resolve the reported compatibility or required-input problem rather than repeatedly reopening the same processing path; the preflight is not a second stacking algorithm.
Performance, memory and concurrency
| Symptom | Explanation and action |
|---|---|
| Only one task appears active | R22 may choose serial execution for a small job, a one-CPU system, insufficient available RAM or scheduler initialization failure. This is an automatic safe fallback. |
| Only two calibration/reprojection tasks run | This is the fixed R22 ceiling for LIGHT calibration, row reprojection and sigma clipping. |
No more than two solve-field processes run | This is the intended astrometry batch limit. Each solver uses an isolated working directory. |
| No thread or memory option exists in Settings | Correct. These values are internal release contracts and are not user configurable. |
| Release behaviour is uncertain | Run python3 validate_performance_release.py; use --json for machine-readable diagnostics. |
See Performance and platform limits for the complete fixed-value table and target-machine checks.
ST/CO pairing and WCCD hand-off
| Message | Interpretation | Action |
|---|---|---|
| No matching comet or stars product | Only one alignment target is present, or grouping metadata do not identify the same reduction. | Create the pair in one WStack run when possible. Keep both products together. |
No matching non-empty PAIRID | The products are not a validated current-schema pair. | Select the reciprocal files produced together; do not combine unrelated legacy products by filename alone. |
Invalid/unsupported PAIRVER or wrong PAIRROLE | The pair schema or roles are inconsistent. | Regenerate the products with the current WStack version. |
PAIRFILE does not point to the selected partner | A product was renamed, moved independently or paired with the wrong file. | Restore the original pair names/location or regenerate. Avoid manually editing only one header. |
| Products are photometrically inconsistent | Filter, method, frame count, pair identity or represented EXPTIME differ. WCCD accepts the Comet/Stars exposure comparison only within 0.001 s. | Use products generated from the same enabled source set and same method. Do not substitute TOTEXP or a manually invented scale for the represented pixel exposure. |
| Stack Browse opens on keyboard focus | R29 opens the chooser on Tab/Shift+Tab only when the receiving Comet/Stars path field is empty. | For a populated path, Tab should only focus the field. Click the field, press Enter/Return or use Browse to intentionally reopen the chooser. Cancel preserves the existing path. |
| Stack Browse immediately reopens | Modal return or duplicate queued requests should be suppressed in R29. | Confirm that the running build is R29 or later. If reproducible, report the exact click/key sequence and whether the path field was empty. |
| Camera dialog opens although the configured camera is correct | Check that Settings contains the native unbinned resolution and that the FITS source dimensions and binning reconstruct the same detector geometry. Exact and unique active-area-compatible matches should be accepted before the dialog is opened. | Correct the camera geometry or FITS binning/source-dimension metadata. The 1370 × 1002, 3 × 3 MI C2-12000A reference reconstructs 4110 × 3006 and must not require confirmation. |
SATCOMP=NONE or source-frame peak provider unavailable | Source-frame saturation provenance is incomplete, but the scalar resolver may still provide a valid effective limit. | Inspect the base, multiplier and effective threshold. Do not reject every star solely for missing provenance; retain flat-top and bleeding morphology rejection. |
| Effective saturation is much larger than 65535 | A SUM or other aggregate image can have pixel values above the per-frame/base detector limit. KOPR scales the base by an integer multiplier so the effective image-domain threshold is not below the finite image maximum. | Verify the base limit and stack method. Do not replace the result with the observed maximum. For the audited 240P SUM stack, 65535 × 16 = 1048560 ADU. |
Comparison scripts
| Symptom | Action |
|---|---|
| Cancel in Load/Save reports an empty filename | This is fixed in R28. Current behaviour is an immediate return with the editor unchanged. |
| A missing comet from Add from list is not available afterwards | Complete the Add Comet dialog. KOPR reloads the record after the dialog; cancelling or failing to add it safely skips that item. |
| Non-ASCII text is damaged in a comparison script | Current script file access uses UTF-8. Verify the file encoding and avoid saving it through software that rewrites it in a legacy code page. |
Catalogues and network services
| Symptom | Action | |
|---|---|---|
0 stars found, looking for online data ... | This is a fallback, not by itself an error. Wait for the terminal result. Verify WCS, field radius, filter and catalogue magnitude limit. | |
| Connection timed out for VizieR, COBS or MPC | Confirm internet/DNS access and retry later. Use local catalogues/data where supported. Do not interpret a network timeout as an empty astronomical field. | |
| Star not found | The catalogue query returned no usable star near the requested coordinates. Verify the position, WCS and catalogue/filter selection. | |
| Elements not found | The local comet database lacks the requested designation. Update orbital elements or correct the designation. | |
| Selected catalogue returned no usable stars | Field, magnitude limit, filter conversion or WCS does not yield calibrators. | Inspect the field and try an appropriate catalogue/limit. Do not force a zero point without accepted stars. |
| COBS rejects or misinterprets an APASS Sloan source | COBS magnitude-source codes are case-sensitive. | Use R47 or later. APASS Sloan g′/r′/i′ must be AG/AR/AI; do not change the case of Gaia identifiers. |
Reference stars are excluded at the 0.150-mag boundary
The R77 policy is strict: every accepted pair must differ by less than 0.150 mag. Exactly 0.150 mag fails. Inspect the scrollable Reference stars dialog to distinguish an observer-disabled star from one rejected by the derived global pairwise solution.
Photometric exposure and background
| Symptom | Cause and action |
|---|---|
| Magnitude changes with local background level | Current R27 photometry subtracts local sky additively but never divides flux by it. Verify that the running build and documentation use net_flux / EXPTIME, not the removed historical sky-ratio convention. |
| Comet and Stars stacks fail exposure preflight | The numerical exposures represented by their pixels differ by more than 0.001 s or required exposure metadata are invalid. Regenerate a matched pair or correct the source metadata; do not force TOTEXP into EXPTIME. |
| A custom photometric scale is requested | R27 has no PHOTSCAL, KPRSCAL or user-entered scale. The accepted observation EXPTIME is the only normalization term. |
ACF, centroid and Review dialog
| Symptom | Cause and action |
|---|---|
| Review comet ACF… is disabled | No successful ACF Comet measurement is retained, or it was invalidated by a new observation/reset/different Comet FITS, a newer successful non-ACF measurement or an incompatible context. Stars-image, reference-star, catalogue and photometric-option changes alone do not invalidate Review. |
| Apply is refused | The preview context_id or run_id no longer matches the active measurement. Close the stale dialog and open Review from the current measurement. |
| Reset returns to the last Apply rather than original Settings | Expected. Reset restores the original or most recently applied state of this measurement; Review parameters are not global Settings. |
| Legacy ACF cut (%) does not alter the production result | Expected. pa-adaptive-upper-v1 uses Upper limit (sigma); the percentage is retained only for legacy rollback. |
| Centroid stops before the brightest nearby pixel | The bounded shift protects the clicked comet identity. Check the click and Comet centroid max shift rather than enlarging the coma aperture. |
| Zoom resets after Measure comet again | R81 preserves the current viewport when the Comet image is already active. The same guard applies to repeated star and tail measurement. A reset is expected only when KOPR must switch to a different image role; report a redraw when the correct role was already active. |
| ACF OFF graph has no clipping curves | Expected. When ACF is disabled, the selected ring has no upper-limit/filtered clipping result to display. |
| ACF ON graph styles appear mixed | Raw, upper-limit and filtered PA profiles should have explicit distinct styles. Capture the selected ring and report the case if the curves cannot be distinguished. |
| Unexpected outer-ring clipping | Inspect the ring map, raw/upper/filtered PA profile and per-ring sigma diagnostics. Only positive PA-local outliers should be clipped; report a case where negative samples are modified. |
| Result changes after Review Apply | Expected only for the ACF profile, plateau/lower-limit decision and final comet flux/magnitude. Catalogue, stars, zero point, centroid and background should remain frozen. |
| Missing reproducibility evidence | Keep the detailed kopr-acf-provenance-v1 diagnostics and confirm a concise KACF line in the log/FITS HISTORY. |
See PA-adaptive ACF and Review dialog for the complete state contract.
Reference stars Use state
| Display | Meaning and action |
|---|---|
| Use is unchecked | The star is not effectively included: it may be disabled by the observer, image-quality-ineligible or rejected by the strict pairwise solution. Read the Reason column. |
| A rechecked star becomes unchecked after Recalculate | Expected when the candidate remains scientifically incompatible. A newly edited/rechecked candidate stays selected only while the new solution is pending. |
| No Pairwise status column exists | Expected in R80. Use shows effective inclusion and Reason is the sole visible exclusion diagnostic; the canonical internal states remain separate. |
Saving and output problems
| Symptom | Explanation |
|---|---|
| CometObs or Afρ text was not appended | The ICQ button appends only the fixed-width ICQ line. Copy/save the displayed auxiliary output separately. |
| Nothing is saved after closing the result dialog | Closing is not an implicit save. |
| Permission error when saving | Choose a user-writable directory and verify that the current KOPR directory is writable for observer-code output. |
| Duplicate ICQ line | The same result may have been reopened/appended from a different dialog or manually copied. The append button only prevents a second click in the same dialog. |
Cancellation and shutdown
Workers use cooperative cancellation. After pressing Cancel, wait for the active external process and cleanup to finish.
| Message or symptom | Action |
|---|---|
| A background operation is still shutting down. Wait a moment and close KOPR again. | Do exactly that. Repeatedly killing the application can leave temporary files or external solver processes. |
| Astrometry or stacking says CANCELLED | Completed immutable products may remain, but the batch/state may be incomplete. Reopen the working directory and review enabled states before retrying. |
| Windows/WSL astrometry remains busy for several seconds after Cancel | KOPR sends TERM to the Linux solver process group, waits up to three seconds, then escalates to KILL. It does not terminate the complete WSL distribution. |
| Suspected orphaned WSL solver | Check inside the selected distribution with pgrep -a solve-field. If a process remains after KOPR has reported completion, include it in the bug report. |
| Index download cancelled | Partial .part files are intentionally retained for resume. |
Prepare a useful bug report
Start with the downloadable bug-report template. For installation/environment issues, run collect-kopr-diagnostics.py from the directory containing kopr.py and attach its text output after reviewing it for local paths.
Always include
- exact KOPR build/archive name and operating system;
- the action sequence that reproduces the problem;
- the complete final error and relevant preceding log lines;
- whether the problem is repeatable with the same files;
- active location, telescope and camera names plus relevant dimensions/binning/filter/exposure;
- expected result and actual result.
For image-pipeline problems
- the relevant frame/group CSV reports;
processing_manifest.json,pipeline_state.jsonand applicable QC JSON;- primary FITS headers and extension inventory for the affected products;
- for paired products, both original ST/CO FITS files and the original source paths when saturation checks are involved;
- for Scientific/Compact issues, include REQMODE/KOPRMODE/STORFMT/QSTEP and all Q-policy keywords plus the validation JSON;
Remove secrets before sharing. Do not attach `.env`, API keys, SFTP credentials or unrelated personal data. FITS headers can contain observer/site information; review them before public publication.
For Windows/WSL astrometry problems
wsl --status
wsl --list --verbose
wsl.exe -d Ubuntu -- sh -lc "uname -a; command -v solve-field; solve-field --help >/dev/null && echo SOLVER_OK"Also include the exact WSL distribution name, whether KOPR logged a native or WSL backend, the final WStack log lines, and the path to the KOPR working directory. Do not include the Ubuntu password.
WCCD Automatic Helpers and Slice
| Symptom | Meaning and action | |
|---|---|---|
| Helper checkboxes are remembered | Expected. Accepted values are persistent defaults stored through QSettings. Cancel must leave the previous defaults unchanged. | |
| New observation was cancelled or failed preflight | No new observation or helper state should be committed, and no helper should start. The previous valid observation remains active. | |
| JPL position unavailable | Check internet and optional astroquery. Continue with the internal KOPR position; the observation must remain open. | |
| JPL object is ambiguous | Confirm the designation/apparition. If no safe match is returned, use the internal position or manual centre. | |
| Expected position is outside the frame | Check time, observatory, object designation and WCS. Use Fix Astrometry or select the centre manually. | |
| Finder or Auto Stars appears inactive | Look for the compact progress dialog and its current stage. The main image intentionally does not show intermediate processing frames. | |
| Auto Star Measure does not start immediately | It waits for the finder worker and candidate dialog. Remain in or later re-enter Measure Stars. | |
| Auto Star Measure failed saturation validation | Check the active image role and policy. With complete NSATVAL, any marked aperture pixel is authoritative and the aggregate stack peak is not a valid substitute. Without a complete map, verify the explicit metadata, detector bit depth, integer storage ceiling or FLOAT fallback. If Saturation level was edited, the role is in manual-threshold policy and intentionally ignores the source-frame map. | |
| A normalized FLOAT image shows Saturation level = 1 | Expected when all finite values follow the common 0–1 floating convention. The data range is used only to recognize that convention. | |
| An unscaled FLOAT image shows Saturation level = 65535 | R47 supplies a generic editable fallback because no authoritative detector metadata are available. Replace it with the actual detector or linearity limit when known. | |
| The displayed saturation value equals the brightest pixel | This is not the R47 policy. KOPR never copies the observed maximum into the threshold field. | |
| Terminal says source-frame provenance is ignored | An explicit Saturation level override is active for the current Comet or Stars image. Restore automatic policy by loading that FITS again; loading the other role does not reset this one. | |
| Only final star markers appeared | Expected. After validation, the main WCCD image shows final catalogue markers and accepted apertures; intermediate overlays remain inside the progress workflow. | |
| Late worker changes nothing | Expected after reset/new observation: observation/source/run-token validation discards stale or cancelled results and prevents a late dialog from opening. | |
| Slice Through Comet unavailable | Set a comet centre first with the finder or manual measurement. | |
| Slice profile remains in a separate window | Expected. Slice is an independent non-modal profile window. Observation reset/replacement closes the obsolete window and clears its selection. | |
| Review remains active on Stars image | Expected. Review belongs to the last successful ACF Comet measurement, not to the currently displayed image. | |
| Review disappeared | Check for new observation/reset/different Comet FITS, a newer successful non-ACF measurement or incompatible context. Stars-image and catalogue changes alone do not invalidate it. | |
| Automatic Comet Finder shows no numerical candidate | The interactive WCCD review still opens a valid WCS/ephemeris cutout and searches to 120 arcsec. | Click the visible comet to create an M1 starting position for the canonical bounded Gaussian centroid, then select it and use Confirm centre. If no review opens, check WCS, time, designation and expected position. |
| Only one row is shown but it is labelled C4 in an older build | The label came from a raw peak number before filtering. | Displayed candidates are renumbered consecutively C1..Cn. Update the application; the row number does not indicate hidden selectable candidates. |
| Clicking the finder image does not select a centre | Pan or zoom mode may be active, or the click was outside the review axes. | Leave pan/zoom mode. Click near a candidate circle to select its row, or click another visible object to create M1. The displayed centre may move within the configured centroid bound because the same Gaussian model is used for every comet-centre route. |
| Candidate review was rejected or closed | No centre or photometric state is committed. | The observation remains available for manual work. |
| Auto Star Measure reports moderate_elongation | The star has elongation above 2.2 and at most 2.7. | This is a quality warning, not an automatic rejection. Standard-shape calibrators are preferred; values above 2.7 are rejected. |
| Stable common-aperture plateau was not found | R55 uses a guarded fallback radius of 3.5 × robust stellar FWHM, never above 4.0 × robust FWHM. | Compare raw and robust FWHM, the robust method/source count and profile-width percentiles. The fallback still passes all normal coverage, saturation, blend, background, S/N, zero-point and scatter gates. |
| Zero-point clipping rejected more than 40% | The reject fraction is diagnostic and no longer fails the result by itself. | Check how many stars remain and the final scatter. At least 3 must remain; 3–7 produces a warning and 8+ continues normally. |
| Auto Star Measure finishes with 3–7 stars | R50 considers this a valid zero point with a prominent warning. | Inspect the final zero point, scatter, rejected reasons and field quality before accepting the result. |
| Auto Star Measure final scatter is high | Scatter up to 0.08 mag is normal; 0.08–0.15 mag is retained with warning; above 0.15 mag is a hard failure. | Use the computed zero point/scatter and rejection list to diagnose catalogue mismatch, gradients, blends, deformation or poor coverage. |
| A few NaN pixels occur in a sky annulus | R55 excludes them statistically while preserving spatial coverage, sector consistency and gradient checks. | A mildly cropped square annulus may pass under stricter coverage or use balanced_boxes only when the failure is geometric/coverage-related. Review the reported background method and precise rejection subreason. |
| NaN or a masked pixel touches the stellar aperture | R55 uses a strict flux-preservation rule: any invalid pixel with non-zero fractional aperture weight causes invalid_aperture. | Choose another star or repair the source product. KOPR does not replace, interpolate or zero-fill missing stellar flux. |
| Raw median FWHM is much larger than robust FWHM | Blended or crowded profiles form a high-width tail. R55 derives the global PSF from isolated quality stars or the lower 30% guarded fallback. | Inspect the FWHM percentiles, method and source count, final aperture, blend gate and post-aperture rejections. A lower robust FWHM is expected when the raw distribution is blend-contaminated. |
| Auto Star Measure reports centroid_failed or invalid_background | R55 records a specific subreason rather than only the generic class. | Use the detailed report to distinguish cropped patches, invalid cores, insufficient valid/background samples, no signal, invalid moments, invalid iterated positions, asymmetric masking, inconsistent sectors, radial gradients or coma contamination. |
All helper failures should leave the manual WCCD route available when the observation itself is valid.