Home › Troubleshooting
Section 13

🔧 Troubleshooting

Advanced

Symptom → cause → fix. Work through these in order. If none of these solve it, the logs and health endpoint will tell you what is actually wrong.

Read the Logs First

Before diving into specific symptoms, check the server logs. Most problems announce themselves clearly in plain text.

bash — systemd (Pi / Linux) 
# Live log tail
$ sudo journalctl -u openhamclock -f

# Last 100 lines
$ sudo journalctl -u openhamclock -n 100 --no-pager
bash — Docker 
$ docker compose logs -f openhamclock
bash — manual npm start 
# Logs print directly to the terminal — scroll up or pipe to a file:
$ npm start 2>&1 | tee openhamclock.log

Also check the health endpoint — it reports API status, connected users, and upstream service health:

bash 
$ curl http://localhost:3000/api/health | python3 -m json.tool

Service Won't Start

Symptom: npm start exits immediately or with an error

Port already in use

Error message 
Error: listen EADDRINUSE: address already in use :::3000

Cause: Something else is already listening on port 3000 (or 3001 in dev mode).

Fix: Find and stop the conflicting process, or change OpenHamClock's port:

bash 
# Find what is on port 3000
$ lsof -i :3000        # macOS / Linux
$ netstat -ano | findstr :3000   # Windows

# Or change the port in .env
PORT=8080

Node.js version too old

Error message 
SyntaxError: Unexpected token '?'
  or: Cannot use import statement

Cause: Node.js version is below 20. OpenHamClock requires Node.js 20 or later.

Fix:

bash 
$ node --version    # must show v20.x.x or higher

# Install Node.js 22 LTS via nvm (Linux/macOS/Pi)
$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
$ nvm install 22 && nvm use 22

Missing .env file

Cause: .env was deleted or never created.

Fix: Copy the example back and set your callsign:

bash 
$ cp .env.example .env
$ nano .env    # set CALLSIGN and LOCATOR

Map Not Loading

Symptom: Grey or blank area where the map should be

Cause A: Browser cannot reach the map tile server (OpenStreetMap CDN). This happens on restricted networks (e.g. corporate firewalls, some hotel Wi-Fi).

Fix: Switch to a different base map tile source in Settings → Map → Base Map, or check if your network blocks external CDNs.

Cause B: JavaScript error in the browser.

Fix: Open your browser's developer tools (F12), go to the Console tab, and look for red errors. Copy the error text and search the GitHub Issues.

No DX Spots Appearing

Symptom: DX Cluster panel is empty or shows "No spots"

Cause A: DX cluster source is unreachable.

Fix: Check the health endpoint for cluster status. Try switching DX_CLUSTER_SOURCE in .env to hamqth as a fallback:

.env 
DX_CLUSTER_SOURCE=hamqth

Cause B: Filters are hiding all spots.

Fix: In the DX Cluster panel toolbar, click ALL to reset all band and mode filters. Check that the continent and zone filters are not excluding everything.

Cause C: Spot retention window is set too short.

Fix: If SPOT_RETENTION_MINUTES is set to a very low value (e.g. 1), spots expire before you see them. Set it to at least 15.

WSJT-X Not Connecting

Symptom: WSJT-X panel shows no decodes, or "Waiting for data…"

Cause A: WSJT-X UDP Server is not enabled or is pointed at the wrong address.

Fix: In WSJT-X: File → Settings → Reporting. Verify:

Cause B: Firewall is blocking UDP port 2237.

Fix:

bash — Linux firewall 
$ sudo ufw allow 2237/udp

On Windows, check Windows Defender Firewall → Inbound Rules for a rule blocking UDP 2237.

Cause C: WSJTX_ENABLED is not set to true in .env.

Fix: Add WSJTX_ENABLED=true to .env and restart.

Rig Bridge Issues

Symptom: Rig Control panel shows "Disconnected" or no frequency

Cause A: Wrong serial port or baud rate.

Fix: Double-check the port name and baud rate in your .env or rig-listener arguments. The correct baud rate is in your radio's CAT/CI-V menu — common values are 4800, 9600, 19200, 38400. Icom CI-V defaults to 9600.

Cause B (Linux): Permission denied on serial port.

Fix:

bash 
$ sudo usermod -aG dialout $USER
# Log out and back in for the group change to take effect

Cause C: Icom CI-V address mismatch.

Fix: Check the CI-V address in your Icom radio's menu (usually under "Connectors" or "CI-V"). Common addresses: IC-7300 = 0x94, IC-705 = 0xA4, IC-9700 = 0xA2. Set RIG_CI_V_ADDRESS in .env to match.

Slow Pi Performance

Symptom: Dashboard is sluggish, panels take a long time to update

Cause A: CPU throttling due to heat.

Fix: Check CPU temperature and throttle status:

bash 
$ vcgencmd measure_temp
$ vcgencmd get_throttled   # 0x0 = no throttling; anything else = throttled

If throttled: add a heatsink or active cooling. Pi 4 and 5 run warm under load — a small fan makes a significant difference.

Cause B: Too many browser panels open on a Pi 3B+.

Fix: Reduce the number of active panels in Settings → Panels. Disable panels you do not use (DXpeditions, Contests, WWBOTA, etc.) The Pi 3B+ has limited RAM — fewer active panels = faster rendering.

Cause C: SD card is slow.

Fix: Use a Class 10 / A1-rated microSD card, or better yet move the OS to a USB SSD. SD card I/O speed is the most common Pi bottleneck for Node.js apps.

Getting More Help

If none of the above fixes your problem, the following resources are available:

GitHub Issues github.com/accius/openhamclock/issues — Search existing issues first. When opening a new issue, include your OS, Node.js version, browser, and the relevant section of your server log.
Health endpoint http://your-instance:3000/api/health — returns a JSON object with server version, uptime, connected users, and the status of every upstream data source. Paste this into your issue report.
Browser console Press F12 in your browser → Console tab. Red errors here indicate frontend JavaScript problems. Include the full error text in your report.