Skip to content

Troubleshooting

Jump to bottom
accius edited this page Mar 5, 2026 · 1 revision

Troubleshooting

Frequently Asked Questions

Do I need an amateur radio license? No. OpenHamClock is a receive-only dashboard. Anyone can view DX spots, space weather, and POTA activations. A callsign is needed for PSKReporter data and DX cluster login.

How much bandwidth does it use? Very little. All external API calls are cached server-side with gzip compression. Typical usage is under 1 MB/minute.

Can I run this on a Raspberry Pi 3? Yes. Pi 3B/3B+ works fine, though initial build is slower (~5 minutes). Pi 4 or 5 recommended. Server uses ~100–150 MB RAM.

Can multiple people use the same server? Yes. Each browser session has its own filters, theme, and DX target. The server caches all API responses so additional users add zero load on upstream services. Use Profiles for different operator configurations.

Can I use JTDX instead of WSJT-X? Yes. JTDX uses the same UDP protocol. Configure the same way (address: 127.0.0.1, port: 2237).

Common Issues

No DX Spots Appearing

  1. Check that your callsign is set — the DX cluster uses it to log in
  2. Verify internet connectivity
  3. If using a custom cluster, confirm the Source dropdown is set to "Custom Telnet Server" (not just Proxy)
  4. Check server logs: journalctl -u openhamclock -n 50 | grep "DX Cluster"

PSKReporter Shows No Data

  • Ensure your callsign is set correctly
  • Check if MQTT is connected (panel footer shows connection status)
  • Some corporate firewalls block WebSocket connections — the system falls back to HTTP automatically

WSJT-X Decodes Not Appearing

  • Verify WSJTX_ENABLED=true in .env
  • In WSJT-X: Settings → Reporting → UDP Server should be 127.0.0.1:2237
  • If on different machines, use the OpenHamClock machine's IP and ensure HOST=0.0.0.0 in .env
  • Check that UDP port 2237 is not blocked by a firewall

POTA Spots Not on Map

Spots appear in the panel list but may not show on the map if coordinates couldn't be resolved. The POTA API provides coordinates for almost all parks, with grid-square fallback.

TCI Connection: "tciSocket.on is not a function"

The TCI WebSocket code needs to use addEventListener() instead of .on() for compatibility with Node.js 21+ native WebSocket. Update your rig-listener to the latest version.

Icons/Emoji Showing as Boxes (Linux/Pi)

Install the Noto Color Emoji font:

sudo apt install fonts-noto-color-emoji

Restart your browser (or reboot in kiosk mode). The Pi setup script installs this automatically.

Chromium Keyring Prompt on Boot (Kiosk Mode)

Add --password-store=basic to the Chromium launch line in kiosk.sh. The latest Pi setup script does this automatically.

Can't Find the .env File

Files starting with . are hidden by default. Use ls -la in a terminal, or Ctrl+H in a Linux file manager. If it doesn't exist, run npm start once (it auto-creates from .env.example) or copy manually: cp .env.example .env.

Server Returns 500 on SOTA Spots

If the SOTA epoch API (api-db2.sota.org.uk) is temporarily down, the spots endpoint may fail. Update to the latest version which wraps the epoch check in error handling.

N1MM+ QSOs Not Appearing

  1. Verify N1MM_UDP_ENABLED=true in .env and server was restarted
  2. Check server logs for [N1MM] UDP listener on 0.0.0.0:12060
  3. In N1MM+: Config → Configure Ports → Broadcast Data → check Contact
  4. Ensure broadcast address/port match your OpenHamClock setup
  5. Check firewall allows UDP 12060

Rig-Bridge Console Spam (localhost:5555 CORS errors)

The rig-bridge SSE endpoint uses exponential backoff — if rig-bridge isn't running, retry interval increases from 5s → 10s → 20s → ... → 5 minutes max. Update to the latest version if you see constant 5-second retries.

Classic Layout — How to Match Original HamClock

Set LAYOUT=classic in .env or select it in Settings. The Classic layout uses a black background with large colored numeric displays, matching WB0OEW's original HamClock style.

Getting Help

When reporting issues, include:

  • Browser and OS
  • Screen size / layout
  • Server logs (console output or journalctl -u openhamclock)
  • Browser console errors (F12 → Console tab)

OpenHamClock · GitHub · Report an Issue · 73 de K0CJH

Clone this wiki locally