Troubleshooting

macOS — app or recording blocked on first install

Release builds from GitHub are not code-signed or notarised. macOS may block OscarWatch or bundled native libraries the first time you run them. These steps are usually one-time per install. See the full walkthrough in macOS install (guide by Tim GW4VXE).

Download OscarWatch-osx-arm64 (Apple Silicon) or OscarWatch-osx-x64 (Intel).
Extract with Finder → Open With → Archive Utility.
Run in Terminal: xattr -d com.apple.quarantine /Users/you/Downloads/OscarWatch/OscarWatch (adjust the path).
Launch the OscarWatch executable; use right-click → Open if Finder blocks it.
For each blocked .dylib, use System Settings → Privacy & Security → Allow Anyway and enter your password (often about three libraries).
Grant microphone access when you enable pass recording in Settings → Recording.

Tracking, passes, and radio/rotator control work without pass recording if you skip the PortAudio step.

MP3 recording says ffmpeg is missing

Install ffmpeg for your OS using the steps in Settings help: Installing ffmpeg.
On Windows, prefer winget install ffmpeg in PowerShell, then fully quit and restart OscarWatch (a new terminal session is also needed for ffmpeg -version to work).
Confirm ffmpeg -version works in a terminal. If the command is not found, ffmpeg is not on your PATH yet.
WAV recording still works without ffmpeg. Open Settings → Recording and choose File format → WAV if you do not want to install it.

Pass times look wrong

Refresh TLEs (Satellites → Refresh TLEs).
Check station latitude and longitude in Settings.
Confirm your PC clock and time zone are correct, or enable Use GPS UTC for satellite tracking under Settings → Integrations → GPS when you have a reliable GPS fix. Choose local or UTC for the main window under Settings → Appearance → Times shown in (pass planner has its own control).

No frequencies / wrong mode

Select the satellite on the map or pass list.
Pick a transponder mode in the frequency panel.
Edit or add the satellite in Manage transponder database.
If the TLE catalogue uses a different name from your database entry, set the NORAD ID and/or alternative names so frequencies still resolve. See preferred names and alternative names.

Map still shows the old satellite name

Change the preferred name in Manage transponder database, then press Save and close the editor so the map and pass list refresh.
Map labels come from the transponder database when a matching entry exists; otherwise they stay on the TLE catalogue name.

Rotator or radio not connecting

Check the serial port in Settings — on Windows, use Device Manager to see which COM port appears when you plug in USB. On Linux, see Linux serial ports if ttyUSB numbers changed after reboot.
Ensure radio, rotator, and GPS (if used) each use a different port.
Close other applications using the same port.
Leave Standby if you expect tracking. Press Resume tracking for live operation. The sidebar heading says Standby, not Live, while it is on.
Settings or the sidebar may show a COM port conflict warning if two devices share one port.
If the port appears but CAT is flaky, try a different USB–serial adapter — see USB serial adapters.

USB serial adapters (FTDI vs Prolific)

OscarWatch talks to many radios and rotators over USB serial. The adapter chipset matters more than most operators expect.

Prefer a genuine FTDI USB–serial cable or the radio’s own USB CAT/CI-V port when it provides one.
Silicon Labs CP210x adapters are usually fine.
Avoid cheap Prolific clones — they are a frequent cause of missed CAT commands, timeouts, and ports that stop working after a Windows driver update. Genuine Prolific devices are less common in bargain cables.
Some very cheap CH340 leads are also unreliable for dense CAT traffic (Doppler updates, dual radio).

FTDI is a recommendation, not a hard requirement — built-in USB on modern rigs (for example IC-9700 or FT-991) is fine. If CAT seems intermittent with an external adapter, swapping to a known-good FTDI lead is one of the fastest checks.

Linux — serial port changed after reboot

Do not rely on /dev/ttyUSB0 staying the same — use /dev/serial/by-id/… or a udev alias (for example /dev/USB821H).
In Settings, press Refresh, then select or type the stable path and Save.
Ensure your user is in the dialout group, (or uucp on an Arch derivative distro) sudo usermod -aG dialout $USER, then log in again.
Close other programs using the same port (Hamlib, gpsd on that tty, other CAT apps).

Full walkthrough: Linux serial ports.

GPS not connecting or no fix

Enable GPS under Settings → Integrations → GPS.
Serial: pick the correct port (Device Manager on Windows; stable by-id or udev path on Linux — Linux serial ports), match baud rate (often 4800 or 9600), and use a port not shared with radio or rotator.
gpsd: set host and port (default 2947), confirm gpsd is running and reachable on the network (gpsmon host:port on Linux is a quick check).
Use Refresh status after saving.
Close other applications that might have the GPS port open.
Wait for a clear sky view or check the GPS has a valid NMEA output (GGA/RMC).
Status bar GPS red = no fix; green = fix active. GPS Time red means time sync is on but GPS UTC is not available yet.
Apply fix to station is only available when a fix is active (green GPS).

CAT frequencies not updating

Check Pause CAT is off in Settings → Radio.
Confirm you are not in Standby mode.
Verify rig type and CI-V address (ICOM).
Try a genuine FTDI USB–serial adapter if you use an external lead — see USB serial adapters.
For cross-band modes, the radio should be in satellite/split layout (OscarWatch usually sets this at pass start).
For receive-only modes (e.g. ISS SSTV with uplink 0), satellite mode should be off on ICOM rigs — OscarWatch does that automatically. On the TS-2000, receive-only stays in SATL with downlink Doppler on FA only — see Kenwood help. Pick the matching band mode (SSTV VHF vs UHF) in the frequency panel.
On linear SSB/CW, check Doppler thresholds — very large values can make tracking look sluggish near TCA.

FlexRadio is discovered but not controlled

Discovery alone does not test control. In Settings → Radio, select the FlexRadio and run Test SmartSDR connection (TCP port 4992 to the radio).
Confirm the radio is enabled, Pause CAT is off, OscarWatch is not in Standby, and a satellite pass with both uplink and downlink is focused.
A dual-SCU model is required (current series: 8600 / 8600M; also dual-SCU 6000-series such as 6600/6700). At pass start the radio should have full duplex on and separate RX/TX slices.
If both panadapters stick on VHF or both on UHF, OscarWatch normally restores them over the API; if that fails, load a SmartSDR Global Profile with separate VHF/UHF pans, then re-select the satellite. See the FlexRadio guide.
If the status bar reports a FlexRadio satellite setup failure, open the logs folder and include the current log in your report. See the FlexRadio guide.

OscarWatch will not reopen after exit (Windows)

Open Task Manager and check for OscarWatch.exe. If it remains after the window closes, end that task and try again; a full reboot should not be necessary.
A second launch now warns when an existing process cannot activate its window. Include the current log if shutdown was forced after its timeout.
Logs are appended under %AppData%\OscarWatch\logs\; attempting a second launch does not erase the current daily log.

Kenwood TS-2000: no CAT replies / SATL not confirmed

The TS-2000 only sends CAT data when the PC asserts RTS on cables that support it. OscarWatch enables hardware RTS by default — use a straight RS-232 cable or USB adapter that passes RTS through. If your cable has no flow control, turn off Hardware RTS in Settings → Radio.
Match baud 57600 8N1 in Settings and on the radio.
Select SAT on the radio and turn memory mode off before tracking — see Kenwood TS-2000 help.
Close any front-panel menu; the radio may reply ?; while a menu is open.
If SATL is not confirmed, OscarWatch still tracks on FA/FB — check the status bar for a degraded-tracking warning.
OscarWatch exits satellite mode when you disconnect or quit the app, unless Turn satellite mode off when OscarWatch closes is unticked in Settings → Radio. Receive-only (beacon) modes keep SATL and track FA only.
OscarWatch leaves RF power alone unless FT4 is set to lower it to 30 W. Otherwise leave the radio at your preferred watts.

Dual radio not connecting (FT-817 / FT-818 / FT-857 / FT-991 / FTX-1 / IC-705 / IC-905 / IC-7100 / IC-706 series)

Enable Settings → Radio → Dual radio and set a COM port for both downlink and uplink.
FT-817, FT-818, FT-857 / FT-857D, FT-991, FT-991A, FTX-1, IC-705, IC-905, IC-7100, and IC-706 / IC-706MKII / IC-706MKIIG appear only in the dual-radio leg lists. They are not single-rig types.
Yaesu FT-817/818: match menu #14 baud (suggested 4800; 38400 also works).
Yaesu FT-857/857D: use the rear CAT/LINEAR jack; set menu 019 to CAT and match menu 020 CAT RATE (suggested 4800; 9600 and 38400 also work).
Yaesu FT-991/991A: match menu 031 CAT RATE (suggested 38400); 8N2 with hardware RTS; use the USB CAT COM port.
Yaesu FTX-1: match menu CAT-1 RATE (suggested 38400); 8N2 with hardware RTS; use the Enhanced COM (CAT-1) port, not CAT-2.
IC-705: CI-V address A4 unless changed in the radio menu.
IC-905: USB CI-V serial; match baud (default 115200); CI-V address AC unless changed in Set mode.
IC-7100: CI-V Output (USB) On (or REMOTE jack); match baud (default 19200); CI-V address 88H unless changed in the radio menu. HF/6 m, 2 m, and 70 cm (not 23 cm).
IC-706 series: CI-V via REMOTE jack; pick the correct leg type — default addresses 48H (706), 4CH (MKII), 58H (MKIIG); baud 19200; CI-V TRN On.
Close Hamlib or other CAT applications using either COM port before starting OscarWatch.
After switching from another rig (e.g. IC-910), quit OscarWatch, replug USB, and restart if CI-V or CAT stops responding.

FT-817 / FT-818: downlink stuck, uplink tracks

Use Full doppler in the frequency panel (not TX-only or RX-only).
On linear SSB, spin the downlink to find the signal, then pause ~1 s so passband trim is captured before doppler resumes.
On FM, the dial is locked via CAT during tracking — use Pause CAT in Settings if you need to tune manually.

ICOM: radio stays on Sub or uplink lags after tuning

On IC-910 / IC-9700 / IC-9100 / IC-821H in satellite mode, OscarWatch keeps you on Main for receive while you turn the dial on linear passes. Uplink (Sub) CAT is intentionally delayed after you stop moving Main so scanning the passband does not select Sub. The wait is Settings → Radio → Uplink CAT wait after dial (default 2500 ms). How soon receive Doppler CAT resumes is Resume CAT after dial (default 800 ms). If uplink seems late right after a long tune, wait a moment or lengthen those values. If Sub stays selected with no pass running, press Resume tracking if Standby is on, or turn satellite mode off and on on the radio. See spinning the dial in Doppler tuning help.

Voice announcements silent

Enable voice in Settings → Voice and set trigger elevation.
On Linux, install espeak-ng (recommended) or espeak. If neither is present, speech-dispatcher with spd-say is used instead.
Use Test announcement in Settings → Voice after installing TTS packages.

Pass recording not working

Enable recording in Settings → Recording and press Save.
Select an input device — your radio line-in or USB audio interface, not the default microphone unless that is what you use.
Press Refresh on the device list if you plugged in hardware after opening Settings.
Use Test recording (5 s) to confirm audio levels before a pass.
Recording only runs for the focused satellite — click it on the map or pass list first.
Check start/stop elevations: the satellite must rise through the start elevation while selected.
On Linux, ensure PulseAudio or ALSA is running (libasound2 on Debian/Ubuntu).
On macOS, see macOS install if libportaudio.dylib is blocked; grant microphone permission when prompted.
Recordings save to %AppData%\OscarWatch\recordings\ unless you chose another folder. Audio files are not auto-deleted; remove old clips yourself if the folder grows large.

Logs

Help → Open logs folder opens %AppData%\OscarWatch\logs\. Log files help diagnose CAT and rotator errors. API keys are not written to logs. Daily oscarwatch-*.log files are retained for 14 days. Optional Doppler pass CSVs under %AppData%\OscarWatch\doppler-logs\ use the same 14-day retention (see Doppler pass insights).

Still stuck?

Open a Bug report on the GitHub issue tracker (the template asks for version, steps to reproduce, and diagnostics). Before you submit:

Help → Copy diagnostics — paste the clipboard bundle into the issue (redacted settings, rig/rotator status, and a log tail).
Help → Open logs folder — attach the daily log file for the day the problem occurred (oscarwatch-YYYYMMDD.log), or paste a relevant excerpt.
Note your OscarWatch version (Help → About), operating system, and radio/rotator models.

See also the project README. For ideas rather than bugs, use the Feature request or General issue templates on the same page (questions, transponder data, translations, and similar).