Troubleshooting

The universal first step for the server and desktop apps: run from a terminal with logging on.

RUST_LOG=info ./run.sh            # both the server and GUI bundles ship run.sh
RUST_LOG=debug ./run.sh           # protocol-level detail

(Windows: set RUST_LOG=info then run the .bat / .exe from a terminal.)

Installing & launching

macOS: “PodSDR can’t be opened” / app is killed immediately. The bundles are ad-hoc signed, not notarized. Right-click → Open once, or clear quarantine: xattr -dr com.apple.quarantine PodSDR.app (for the server bundle: xattr -dr com.apple.quarantine . inside the bundle directory).

Linux GUI won’t start. Needs glibc 2.31+ (Ubuntu 20.04 / Debian 11+), an X11 or Wayland session, ALSA/PulseAudio, and ideally a Vulkan-capable GPU (wgpu falls back to GL). RUST_LOG=info ./run.sh shows which piece is missing.

Windows: window never appears. Run podsdr-gui.exe from a terminal with RUST_LOG=info; the GUI wants a DirectX 12-capable GPU/driver.

Browser & web client

Certificate warning on every visit / “connection not private”. Expected once per browser profile with the self-signed certificate. If it never sticks, or you connect by an address that isn’t in the certificate, restart the proxy with --tls-san <your-ip-or-hostname> after deleting the old cert.pem/key.pem (they’re next to the proxy binary).

ERR_SSL_PROTOCOL_ERROR. You opened https:// but the proxy is running without --tls (plain HTTP). Use http://, or start with TLS (the default run.sh does).

No microphone / MIDI / choppy audio over plain HTTP. Browsers withhold mic capture, WebMIDI and low-latency audio outside a secure context. Serve over HTTPS (the default) or via http://localhost only.

Radio list is empty in the browser. Check /api/devices on the proxy (e.g. curl -k https://pi.local:8080/api/devices). If it’s empty, the proxy can’t see the radio: same subnet? UDP 1024 open? For radios on other subnets add a manual host.

Radio & connection

Desktop GUI doesn’t find the radio / emulator. Both ends must be on the same broadcast domain. If discovery lands on the wrong interface (VPNs), use Discover at IP, or start the emulator with --bind <lan-ip>.

Emulator fails to bind port 1024 on Linux. sudo setcap 'cap_net_bind_service=+ep' ./podsdr-emu (or run it once with sudo).

Emulator connects but I hear only noise. That’s what it produces by default. Start it with --echo or --echo-live to hear your own TX back — see Using the emulator.

“session limit reached” from the proxy. More concurrent clients than --max-sessions (default 32). Raise it, or wait — dead sessions are reaped within ~30 s.

Second client can’t connect to a CAT radio. Serial ports are exclusive; one control session per CAT radio at a time. Cloud listener roles can still monitor.

PTT greyed out / button reads “RX ONLY”. You’re tuned inside a configured receive-only range (or connected with a listener role). See receive-only bands.

Cloud

No pairing code in the console. Codes are only issued while the proxy is unclaimed. If it was claimed before (message: already claimed), connect with the owning account, or look in the logs: journalctl -u podsdr-proxy | grep "with code:".

Proxy refuses to start the uplink (“hub public key”). A non-localhost broker requires --hub-public-key. Get it from your broker deployment (the public bundles bake in the public broker’s key); --insecure-open-mode bypasses the check for development only — it gives every client TX rights.

Proxy shows online but connect fails from far away. Give it a moment — TURN relaying (including over 443) engages automatically on restrictive networks. Check the client-side stage label for where negotiation stops.

CAT radios

Serial port won’t open. Is the radio powered on and the cable in? Is another program (logger, WSJT-X) holding the port? The proxy retries the open briefly, then logs an actionable error. The web config panel and podsdr-proxy configure can autodetect the right port.

TX audio too quiet/loud on a CAT rig. Adjust tx_audio_gain_db (also live from the client’s TX-Audio panel); RX level via rx_audio_gain_db.

Icom scope panadapter is jerky. Raise the CI-V baud rate (e.g. 115200) on both the radio and the config.

Settings

All clients move a corrupted settings file aside (*.corrupt.<timestamp>) and start with defaults, telling you about it — nothing is silently lost. “Wipe all settings” (discovery screen) and “Reset All Settings” (desktop Settings → System) are the explicit resets.