DXChrono Desktop

Help → Troubleshooting

Quick checks first

• Confirm a license key is saved (Settings → License, or the first-run license dialog).
• Confirm your station callsign is set in Settings → Station (not NOCALL).
• Confirm your PC has internet access and your firewall allows DXChrono outbound connections.
• Press R to force a data refresh, then wait for normal refresh intervals from Settings → Data.
• If data is stale, verify your refresh intervals are not set very high.

Update checks (new version reminder)

The app compares your running version to a small file on desktop.dxchrono.com. It does not send your callsign or logbook data. If checks never seem to work:

• Confirm the PC has normal web access (try opening desktop.dxchrono.com in a browser).
• Some club or corporate networks block unknown HTTPS sites—ask the network admin to allow desktop.dxchrono.com, or run the check from home or phone hotspot once.
• Open Settings → Data, click Check for Updates, and read the message at the bottom of the Settings window (green = you are up to date; amber = the check could not finish).
• If you do not want automatic checks, turn off Check for app updates on the same tab and watch the download page for new releases.

Full options are described under Settings → Data → Software updates.

License: Activate or Validate fails

• Check that the key is pasted exactly (no extra spaces); copy from the purchase email again if unsure.
• Confirm the PC has internet access. A strict firewall or some shared networks can block license checks.
• Too many computers – A license key usually allows up to five PCs. If you see a device limit message, check your order email for how to manage activations, or contact where you bought DXChrono for help.
• If Validate license when app starts is on and something fails in the background, open Settings → License and use Validate or Activate to see the message in the app.

No data or map overlays updating

• Open Settings → Data and check refresh intervals (solar, bands, aurora, gray line, Cloudlog, ADIF Logbook, QRZ Logbook).
• If only one data source is missing, check that specific service endpoint and credentials.
• If everything is missing, check local network/firewall/proxy policy first.

Cloudlog test fails

• Use the base URL without a trailing slash (for example https://log.example.com).
• Generate/verify API key in Cloudlog (Admin → API Keys).
• If recent QSOs are empty, verify your public slug setup (if used).
• Test the same URL/API key from a browser or curl on the same machine.

QRZ Logbook: no markers or empty map pins

• Confirm Logbook on the QRZ tab succeeds (STATUS). FETCH needs Logbook API access on your QRZ account.
• Ensure Show QSOs on map is enabled on the QRZ tab.
• Map placement needs a gridsquare or lat/lon fields in the QSO record QRZ exports; if your log entries lack a locator, pins cannot be placed.
• Try a wider FETCH date span or higher FETCH max records if you expect contacts outside the default window.
• When running from a terminal, enable Print FETCH response preview on the QRZ tab (or set DXCHRONO_QRZ_DEBUG_ADIF=1) for a short ADIF preview in the console; the API key is not printed.

QRZ XML lookups (DX Cluster / Reverse Beacon)

• Use footer XML on the QRZ tab to verify your website username and password (this is separate from the Logbook API key).
• Enable XML lookup: DX Cluster spots and/or XML lookup: Reverse Beacon skimmers only where you need them; each uses your QRZ XML subscription quota.
• Lookups run only when the prefix table returns no coordinates for that call—ordinary spots still use the built-in data.
• If lookups time out on slow links, raise DXCHRONO_QRZ_XML_TIMEOUT (seconds, default 12). Grid refinement after CTY already found a country uses a shorter cap: set DXCHRONO_QRZ_XML_REFINE_TIMEOUT (seconds) if you need it higher or lower.
• After many days running, the app re-issues a QRZ login on a timer (default 20 hours). To change that interval, set DXCHRONO_QRZ_XML_SESSION_MAX_SEC (seconds); use 0 to disable proactive refresh (not recommended).

ADIF Logbook file: no markers or panel not updating

• Open Settings → ADIF and confirm Enable ADIF Logbook file is on.
• Check the file path (use Browse to avoid typos) and confirm the file exists and is readable.
• Ensure your ADIF records include a gridsquare or lat/lon fields for map pin placement.
• If your logger rotates files, update the path to the currently active .adi file.
• Verify Settings → Data → ADIF Logbook refresh interval is not set too high for your workflow.

N1MM data not appearing

• In DXChrono: Settings → N1MM, enable N1MM+ UDP and confirm port/address.
• In N1MM Logger+: Config → Config Ports and enable Broadcast Data to the same UDP port (default 12060).
• Ensure local firewall allows inbound UDP on that port.
• If using another host, verify the listen address and network route.

DX Cluster connects then drops

• Double-check host, port, and login callsign.
• Try a different cluster host to rule out server-side limits/outage.
• If your network has strict idle timeouts/NAT, shorter reconnect cycles may be expected.
• Add backup cluster profiles in Settings → DX Cluster so the app can fail over to another host; read the DX Cluster widget status line (and the D command window banner) to see connect, failover, or reconnect progress.
• Use the DX command window (D) to confirm command/response flow.

PSK Reporter connected but no spots

• Set a real station callsign in Settings → Station (not NOCALL).
• Confirm you enabled at least one stream: “who's hearing me” and/or “who I'm receiving”.
• Verify MQTT host/port/TLS combination (1883 plain, 1884 TLS).
• Remember spot flow depends on on-air activity and report timing.

Linux/Wayland display issues

• If you see a black/flickering window, try windowed mode first (--windowed).
• Update GPU drivers and SDL/pygame packages from distro repos.
• On Raspberry Pi, test with the recommended build and current OS updates.

Slow startup or heavy map load (low RAM)

DXChrono can use a large NASA-style world picture in the assets folder. On a PC or Raspberry Pi with only a few gigabytes of RAM, loading that picture at full detail for the first screen can take a long time and make the computer feel unresponsive. The app now detects typical low-RAM setups and uses a lighter path automatically so the map and globe still look fine at normal zoom, with a practical limit on how sharp extreme zoom-in can be.

Settings: open Settings (S) and use the Performance tab for the same options (map memory mode, RAM cutoff, optional pixel caps, resize quality). Click Save so the map reloads with the new behaviour. Until performance exists in your saved config.yaml, only the environment variables below apply at startup. After Performance is saved, Map memory mode → Auto clears a previously forced mode from the environment for that run so RAM-based detection can apply.

Environment variables (optional; set before launch if you prefer not to use Settings):

• DXCHRONO_LOW_MEMORY_MAP=0 — treat the PC like a high-RAM desktop: full-detail map loading (slower and heavier on small machines; use if you have plenty of RAM and want maximum zoom sharpness).
• DXCHRONO_LOW_MEMORY_MAP=1 — force the lighter path even on a powerful PC (for testing or if you want to limit memory use).
• DXCHRONO_LOW_MEMORY_MAP_RAM_MB — change the RAM cutoff in megabytes (default 4096). Only applies when you are not forcing 0 or 1 above.
• DXCHRONO_MAP_MAX_DECODE_PIXELS — upper limit on how many picture elements are held during loading on the lighter path (default 9000000).
• DXCHRONO_MAP_MAX_HI_PIXELS — upper limit for the extra detail layer used when you zoom the 2D map in (default 7000000 on the lighter path).
• DXCHRONO_MAP_RESIZE_QUALITY — fast (default on the lighter path), best, box, or bilinear: trades a little sharpness for speed when shrinking the world picture.

If RAM cannot be read (unusual), Linux on ARM boards may still use the lighter path as a safe default.

Crash logs and support info

DXChrono writes crash diagnostics to ~/.dxchrono/crash.log. If you report a bug, include:

• OS and app version
• What you were doing just before the issue
• Relevant section of ~/.dxchrono/crash.log
• Your integration settings summary (without sharing private API keys)