Troubleshooting¶

Common problems and what to check. Paths below assume the default data directory:

OS	Data directory
Linux	`~/.local/share/fbsat59/`
macOS	`~/Library/Application Support/fbsat59/`
Windows	`%APPDATA%\fbsat59\`

The database is fbsat59.db inside it. The log file path is printed to the console at startup ([FBSAT59] Log file: …).

Startup¶

Won't launch — run it from a terminal to see the error. On Windows, plain Windows 8 (not 8.1) fails with a missing DLL; install on 8.1 or later. As a last resort, quit and move fbsat59.db aside so it rebuilds.

Splash hangs at "Fetching TLE data…" — this needs internet. Give it a minute or two; CelesTrak can be slow or briefly down. If it never finishes, quit and relaunch — the app starts with whatever TLE it already has.

Satellite tracking¶

No satellites / empty pass list¶

Check your location — File → Set QTH…. Coordinates in decimal degrees, correct hemisphere, sane elevation.
Update TLE — Satellite → Update TLE, and wait for it to finish. Right-click a satellite → Satellite Info… to see its TLE epoch.
Check the list filter — if it's set to a group or Hidden, widen it to All Satellites.

Position or pass times look wrong¶

Stale TLE — update it (above). ISS is a good reference to sanity-check against.
Wrong QTH — even 1° of latitude/longitude error moves pass times by minutes.
Times in the "wrong" zone — that's just the display setting: View → Time Zone (UTC / Local Time).

Radio Control issues¶

"Serial port not found" / won't connect¶

Check the USB/CAT cable; try another port.
Install the rig's USB driver if the OS doesn't provide one.
Confirm the port: Linux ls /dev/ttyUSB* /dev/ttyACM*; macOS ls /dev/cu.*; Windows Device Manager → Ports (COM & LPT).
In Radio → Rig Settings… set the port with Scan, match the Baud Rate to the rig's CAT setting (the Test button checks it), and pick the exact Rig Model (or a close one).

Frequency doesn't change when picking a transponder¶

The status bar must show RIG: 1 (or 1+2). If not, connect on the Radio Control tab with Connect Rig 1.
Check the rig is on the VFO/mode the transponder expects.

Doppler correction seems too large or too small¶

Update the TLE and re-check the QTH — both feed the shift calculation.
Test against ISS.
Expected behaviour: downlink sits above nominal near AOS, ≈0 at TCA, below nominal toward LOS.

Older rig can't keep up / frequency jitter¶

Increase Cycle (ms) on the Radio Control tab (the CAT / Doppler update interval).

SDR issues¶

SDR not detected¶

Plug it in, wait a few seconds.
Radio → Rig Settings… → SDR Settings tab → Enumerate.
On Windows, RTL-SDR and HackRF need the WinUSB driver applied once with Zadig (never libusbK). Only RTL-SDR and HackRF work on Windows — see Setup — Step 3.
On Linux/macOS install the SoapySDR module for your device — the Help → SDR Device Installation… dialog lists the package names.

Waterfall shows nothing¶

Check the tuned frequency is really the satellite's downlink.
Raise the RF gain; check the antenna/feedline.
Sweep ±50 kHz around the expected frequency.

Audio crackling / distorted¶

Lower the RF gain.
Close other CPU-heavy apps.
Try a different / shorter USB cable.

Web interface (mobile) issues¶

Can't connect — same Wi-Fi as the desktop; IP matches the status bar; not a guest/AP-isolated network; try http://localhost:8080 on the desktop itself. The port is fixed at 8080.
Sluggish radar — Wi-Fi signal, other browser tabs, desktop CPU load.
Compass does nothing — grant the browser's motion/orientation permission; on iOS the page must be HTTPS; recalibrate with a figure-8 motion.

Database¶

"Database is locked" — quit any second copy of FBSAT59, then relaunch. If it persists, quit and move fbsat59.db aside (a fresh one is built on next launch; TLE and transmitter data re-download). Back it up first if you want to keep your favorites and settings.

Getting more help¶

Logs — the file named at startup ([FBSAT59] Log file: …), under the platform log directory.
Bug reports — GitHub Issues: what you did, what you expected, what happened, your OS and FBSAT59 version, and the relevant log lines.
Questions — GitHub Discussions.