Troubleshooting

Most SkyTracker problems come down to four things: the SDR isn't seeing RF, the decoder isn't feeding the agent, the agent can't reach the platform, or the enrichment database hasn't downloaded yet. Here's how to diagnose each.

Read the logs first

sudo journalctl -u skytracker -f
# and, if readsb was installed by us:
sudo journalctl -u readsb -f

Most problems shout at you from these logs. Keep them open while you try the fixes below.

No aircraft are showing up

Is the decoder seeing signals?

Open http://<device-ip>/tar1090/ (or whatever web UI your decoder ships). If you see aircraft there, the problem is SkyTracker → decoder. If you don't, the problem is SDR → decoder.

SDR not seeing signals

  • Confirm the dongle is detected: rtl_test -s 2400000. It should list the tuner and spin for a few seconds without errors.
  • Check the antenna connection. An SMA connector tightened finger-tight is a surprisingly common culprit.
  • Move the antenna to a window or outdoors. Indoor placement often sees nothing, especially at lower elevations.
  • Check gain — if signals are saturating, try lowering it in readsb's config.

Decoder not feeding the agent

  • Confirm aircraft.json is live: curl -s http://localhost/tar1090/data/aircraft.json | head
  • Confirm the path matches your config. For piaware/dump1090-fa, the path is /dump1090-fa/data/aircraft.json, not /tar1090/....
  • See Running Alongside Other Feeders for the correct URL per feeder.

Aircraft appear but have no registration or type

SkyTracker enriches aircraft using wiedehopf's tar1090-db, which is downloaded on first boot and refreshed weekly. If enrichment is missing:

  • Check that the enrichment download succeeded: ls -la /opt/skytracker/data/ — you should see a recent aircraft.csv.gz.
  • If missing, trigger a manual refresh: sudo systemctl restart skytracker (the agent re-downloads on start if the local copy is missing or older than a week).
  • Check firewall / DNS — the agent fetches from raw.githubusercontent.com.

Enrichment covers most civilian aircraft but not every military or obscure airframe. If the agent can't identify an aircraft, the display shows the raw ICAO hex.

GPS not locking

See GPS Setup for the detailed fix list. The quick version:

  • Give the receiver a clear view of the sky.
  • Allow 30–60 seconds for a cold fix; first-ever boot can take several minutes.
  • If you don't need a dongle, pin coordinates via SKYTRACKER_LAT / SKYTRACKER_LON instead.

Wi-Fi setup problems

If you installed SkyTracker on a fresh Pi that didn't pick up your Wi-Fi network, the easiest fix is the standard Raspberry Pi route: 

sudo raspi-config
# → 1 System Options → S1 Wireless LAN

Or edit /etc/wpa_supplicant/wpa_supplicant.conf directly. Once online, the agent will resume normally — no SkyTracker-specific Wi-Fi config.

If you're using the companion mobile-app BLE provisioning flow, follow the on-screen prompts during pairing. Failed pairings reset after 5 minutes by default.

Station shows offline on skytracker.ai

  • Verify the agent is running: sudo systemctl status skytracker.
  • Verify it can reach the platform: curl -s https://api.skytracker.ai/health.
  • Check the sharing mode — a Private station never contacts the platform, so it will always appear offline there. See Sharing Preferences.
  • If the station was claimed, confirm the API key is present in /etc/skytracker/config.yaml under platform.api_key.

Display UI won't load on :8888

  • Port in use? sudo ss -tlnp | grep 8888 — something else might be bound. Change display.port in the config.
  • Firewall on the device? sudo iptables -L -n | grep 8888.
  • Agent crashed on startup? sudo journalctl -u skytracker -n 100.

Nothing above helped

Capture a support bundle and email it: 

sudo journalctl -u skytracker --since "1 hour ago" > /tmp/skytracker.log
sudo cat /etc/skytracker/config.yaml >> /tmp/skytracker.log
# email /tmp/skytracker.log to hello@skytracker.ai

(Your API key is redacted automatically from the log by the agent.)