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.
• If you cannot find the purchase email, use Lost your key? on the first-run license dialog or in Settings → License. Enter the same email address you used when buying; the keys are emailed to you.
• 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, tropo, grey line, Cloudlog, ADIF Logbook, QRZ Logbook).
• Aurora overlay: DXChrono tries NOAA first; if that feed is blocked or empty, it falls back to the DXChrono aurora proxy. Press A (or enable Show Aurora Overlay under Settings → Display) and wait for the next refresh, or press R to refresh now.
• Tropo overlay: F5LEN worldwide forecast (current 3-hour slot). Press T or enable Show Tropo Overlay under Settings → Display, then wait for the next refresh or press R.
• SpE overlay (beta): press E or enable Show SpE Overlay (Beta). Check Settings → SpE (Beta) for the server URL, and that the SpE page loads in a browser. For yellow 4 m, the server must include 4 m PSK spots.
• Live HF Band Conditions: confirm Settings → HF Band Conditions is on, check your Worldwide / My grid / Continent / DXCC scope, then press R. If the live service is down, Desktop falls back to the classic feed (no 160 m row).
• If only one data source is missing, check that service and its credentials.
• If everything is missing, check local network / firewall / proxy first.

Solar, aurora, SOTA, or several HTTPS feeds fail at once

If the log shows a missing certificate file (often after the Mac has been asleep or the app has been open a long time), PSK Reporter may still work because it uses a different connection. Quit DXChrono fully and open it again. Current builds keep a copy of that file under your user folder (~/.dxchrono) so this is less likely after you update.

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 / N1MM+)

• 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, XML lookup: Reverse Beacon skimmers, and/or XML lookup: N1MM+ QSOs 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, port 12060, listen address 0.0.0.0, then Save.
• In N1MM Logger+: Config → Configure Ports → Broadcast Data. Enable Contacts (and Radio if you want band info). Port must be 12060 on each enabled line.
• Same PC only? 127.0.0.1:12060 is enough. Raspberry Pi or another machine on the LAN? N1MM must also send to the subnet broadcast, e.g. 127.0.0.1:12060 192.168.1.255:12060 (adjust for your network). 127.0.0.1 alone never leaves the logging PC.
• On the Pi, test while logging a QSO: sudo tcpdump -i any udp port 12060 -n -c 3. No packets means a network or N1MM addressing problem, not DXChrono. If broadcast fails (guest Wi‑Fi), use the Pi’s IP: … 192.168.1.50:12060.
• Ensure the Pi firewall allows inbound UDP 12060 (sudo ufw allow 12060/udp if using ufw).
• Multi-op: All computers on one station re-sends every networked QSO to UDP; it does not replace the IP/broadcast address above.
• Status/Radio works but QSO list empty on a Pi with no internet? N1MM UDP does not need the internet — only LAN delivery. A Pi booted offline may have the wrong date until NTP runs; with Special Event + N1MM that used to hide all “today” contacts. Set the clock before the event (timedatectl) or connect briefly so time syncs. QRZ XML lookup for N1MM is optional and does not block the QSO list if it fails.

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.

A widget is ticked in Settings but I cannot see it

• With many panels on, older builds stacked them off the bottom of the screen or on top of each other, so a ticked widget looked as if it had vanished. Current builds keep those panels on screen and uncover a title bar if another panel was sitting on it.
• Press W to reset the layout to the defaults, then drag panels where you want them. Windowed and fullscreen layouts are stored separately.
• The Watch List panel still hides itself when there are no current matches, and comes back when a match arrives.
• The MUF panel only draws when the MUF overlay is on (M or Settings → Display).

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.

Exit stuck on “Loading map”, or app closes by itself

• Stuck on a black screen with “Loading map” when you try to quit — usually the window manager sent resize events while closing; recent builds ignore those during exit. Use ESC or Q to quit. If a kiosk script auto-restarts the app, stop that script first.
• Back at the desktop after a while — the process may have crashed or been stopped for low memory. Check ~/.dxchrono/crash.log for the time it stopped and share that with support if needed.
• App closed after the monitor woke from sleep (Raspberry Pi / Linux) — some setups send a spurious “close window” signal when HDMI reconnects. Recent builds ignore that while the display was asleep and refresh the map when the screen comes back. If it still happens, check ~/.dxchrono/crash.log for Display hidden, Display wake, or Received signal lines. For kiosk use, disable monitor sleep in the OS or use xset -dpms in your autostart (see the Pi install script).
• On Raspberry Pi, turn off 3D globe auto-spin (O in 3D mode) if the display still feels sluggish. Auto-spin now skips heavy overlays and great-circle lines while turning, and Settings → Map 3D can lower the spin redraw rate to 10 or 15 FPS.

Slow startup or heavy map load (low RAM)

If you are still choosing a machine, see System requirements first (Pi 4/5, 2 GB minimum / 4 GB recommended; typical mini-PCs are a better shack display than HamClock ARM appliances).

DXChrono ships 720p, 1080p, and 4K world pictures plus a large NASA file used only when you zoom the flat map. On a PC or Raspberry Pi with only a few gigabytes of RAM, the app starts from the smaller picture and skips that NASA zoom layer so the first screen is not a long hang. Settings → Performance → Base map size chooses the unzoomed picture (Auto follows the window; Raspberry Pi preset uses 720p).

The first map is drawn as soon as that picture is ready. Solar and HF numbers in the panels may catch up a moment later — they load in the background instead of holding the splash on “Loading solar”, and the map should keep moving while those panels fill.

Settings: open Settings (S) and use the Performance tab. Start with a machine preset (Raspberry Pi, 4 GB PC, or Desktop), then adjust base map size, map memory mode, RAM cutoff, optional pixel caps, globe texture width, and the logbook line cap if you need to. 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.

3D globe looks like a plain blue ball

The globe needs the same world picture as the flat map. Packaged builds unpack that picture into a temporary folder. On a Mac in particular, macOS can clear that folder (the same thing that used to break HTTPS feeds after a long run). A first start just after an update can also miss the picture for a moment. That used to show a message about a missing globe texture and a sphere with no land. Restarting the app often clears it.

Current builds retry the load, keep a small copy of the world picture under ~/.dxchrono (like the HTTPS certificate), look next to the application as well as in the bundle, and show a simple placeholder with rough continents if the picture still cannot be read.

• If it happens once and looks normal after a restart, you can ignore it.
• If it keeps happening, switch to 2D in Settings → Display. If the flat map looks normal (real coastlines, not crude green blobs), the picture is on disk; update to a newer build.
• If both views look like a sketch map, the NASA picture is missing. Packaged releases include 720p / 1080p / 4K files (and world_map.jpg); re-download the app, or copy a Blue Marble JPEG named world_map.jpg into the same folder as the DXChrono executable (or into an assets folder next to it).
• On a Raspberry Pi or a PC with 4 GB of RAM, open Settings → Performance and leave map memory on Auto so the globe uses the lighter picture first.

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)