Skip to main content
Version: 26.10.1

Troubleshooting

This page is the symptom index for AetherSDR. Find the symptom you see below; if it belongs to one feature, the By feature list links that feature's own Troubleshooting section. To report a problem that isn't solved here, see Filing a bug.

Start with the built-in tools:

  • Help → Support & Diagnostics... for logs. See Support and Logging.
  • Tools → Network Diagnostics... for link problems, and Tools → Runtime Monitor... for performance. See Runtime Monitor.
  • Help → Slice Troubleshooting... walks through common slice problems.
  • The Log Analyzer checks a log or support bundle for known problems and links the fix. It runs in your browser; the file is never uploaded.

Connecting​

No radio appears under On This Network​

Discovery broadcasts are not reaching AetherSDR. The radio may be on a different subnet (broadcasts do not cross routers or most VPNs), a firewall may be blocking UDP port 4992, or the radio may enforce private-IP connections while you are on a different network.

  1. Check the radio is reachable: ping <radio-ip>.
  2. Allow discovery through the firewall, for example sudo ufw allow 4992/udp.
  3. Use Connect by IP: choose the Radio type, enter the radio's address and click Connect by IP. See Manual Connection.

The radio refuses the connection​

The radio rejected AetherSDR's GUI-client registration (for example with error F3000001). AetherSDR stops, closes the connection, does not retry on its own, and returns to the connect panel showing the radio's error and what to do about it.

  1. Read the message in the connect panel and follow it.
  2. Typically another client must disconnect first, or the radio needs a restart.

A Connected Stations dialog appears when you connect​

multiFLEX is off on the radio and other clients are already connected.

  1. Disconnect one of the stations listed in the Connected Stations dialog.
  2. See Multi-Flex.

The radio is not registered with SmartLink, or port forwarding is not set up.

  1. Register the radio with SmartLink.
  2. Forward TCP 4994 and UDP 4993 to the radio.
  3. See SmartLink Setup.

The radio's certificate does not match the one AetherSDR pinned.

  1. Read the certificate pinning section of SmartLink Setup before accepting the new certificate.

Audio​

No audio from the speakers​

The panadapter and waterfall run but nothing comes out of the speakers. PC Audio is off, the wrong device is selected, something is muted, or the audio device failed to open.

  1. Check that PC Audio is on in the title bar and that the right Output device is selected under Radio Setup → Audio. See Audio Settings.
  2. Check the slice is not muted, and that the title-bar speaker and master slider are not muted or at zero.
  3. Turn on the Audio log category in Help → Support & Diagnostics... and look for device-open errors.
  4. Linux with PipeWire: if the PipeWire library is installed but PipeWire's client configuration is not, AetherSDR keeps Qt's audio off PipeWire at startup rather than crashing. Install your distribution's pipewire (Arch) or pipewire-bin (Debian/Ubuntu) package.

The audio device lists show only "Dummy Output"​

This affects source builds on Ubuntu and Linux Mint. The AppImage does not need this.

  1. Follow the distro notes in docs/BUILDING.md.

The link has jitter or packet loss.

  1. Raise Radio Setup → Audio → Audio Buffer (default 100 ms) a little at a time.
  2. Leave Smooth packet loss on.
  3. Use Opus compression and low bandwidth mode. See Low Bandwidth Connections.
  4. Watch latency, jitter, packet loss and the audio buffer over time in Tools → Network Diagnostics....

Keyboard​

Space bar or arrow keys do nothing​

Operating keyboard shortcuts (Space for PTT, arrows to tune, and so on) are off by default. While they are off, the first key press that nothing accepts shows "Keyboard shortcuts are off" in the status bar.

  1. Turn them on with Settings → Keyboard Shortcuts.
  2. See Keyboard Shortcuts.

Starting and crashing​

error while loading shared libraries: libOpenGL.so.0​

Ubuntu 26.04 no longer installs libopengl0 by default on the desktop image. AetherSDR's GPU spectrum and waterfall link against libOpenGL.so.0, so it refuses to start without it.

  1. Run sudo apt install libopengl0.

This is the modern GLVND desktop OpenGL runtime, not the legacy libgl1; both can be installed side by side.

The AppImage does not run on Raspberry Pi OS Bookworm​

The ARM AppImage needs glibc 2.38 or newer, and Bookworm has glibc 2.36.

  1. Use Raspberry Pi OS Trixie. See Installation.

AetherSDR crashes opening a dialog under XWayland (GLX BadAccess)​

Some compositors produce this crash under XWayland.

  1. Run natively on Wayland: QT_QPA_PLATFORM='wayland;xcb' ./AetherSDR-*.AppImage.

Problems after a crash while popping out a panadapter​

AetherSDR saves a floating panadapter only after the pop-out succeeds, so a crash during a pop-out does not repeat on the next launch. A stale floating layout can still be left behind.

  1. Use View → Workspace Canvas → Workspaces → Import pop-outs onto canvas to recover it. See Workspace Canvas.

A stored setting stops AetherSDR from starting​

A bad stored value, such as a window placed off-screen, is applied at startup.

  1. Use AetherSDR --config to inspect or remove the value. See Settings and Backups.

AetherSDR crashes on exit with MangoHud​

This is not an AetherSDR bug.

  1. Disable MangoHud: MANGOHUD=0 ./AetherSDR.

Display​

Panadapter is black, blank or drawn wrongly​

The renderer cannot draw on this display or driver.

  1. Headless Linux (VNC, no monitor): AetherSDR detects a Wayland session with no connected display and starts on XWayland automatically. If you have set QT_QPA_PLATFORM yourself, your setting wins: remove it or set QT_QPA_PLATFORM=xcb.
  2. Driver problems: force software OpenGL with AETHER_NO_GPU=1 (no rebuild needed). This is worth trying first on a Raspberry Pi.
  3. Help → About AetherSDR shows which renderer is in use. See GPU Rendering.

Settings​

Your settings came back after you deleted AetherSDR.db​

Deleting AetherSDR.db by hand is not a reset: the next launch re-imports the frozen settings snapshot from your upgrade.

  1. Use Settings → Reset Settings.... It writes a backup first, removes AetherSDR's local settings, then quits. Settings stored on the radio are not affected.
  2. See Settings and Backups.

Reporting a crash​

Every release has matching debug-symbol archives, so a crash report from your computer is enough for developers to find the cause. When you file the issue (Help → File an Issue...), say which download you ran (AppImage, DMG, Windows installer or portable) and attach:

  • Linux: run coredumpctl list AetherSDR, then coredumpctl info <PID> > aethersdr-crash.txt and attach the text file. Do not attach the core file itself. It is a copy of the program's memory and can contain passwords and tokens.
  • macOS: the newest AetherSDR-*.ips from Console → Crash Reports or ~/Library/Logs/DiagnosticReports/. It names your user folder in file paths; edit that out if you prefer.
  • Windows: Windows keeps a crash dump only if local dumps are switched on. In an administrator PowerShell: 
    $k = 'HKLM:\SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps\AetherSDR.exe'
    New-Item -Force $k | Out-Null
    New-ItemProperty -Force $k -Name DumpType -PropertyType DWord -Value 1 | Out-Null
    After the next crash, attach the dump from %LOCALAPPDATA%\CrashDumps\ (AetherSDR.exe.<pid>.dmp).

The full guide is docs/debugging-crashes.md.

Filing a bug​

If nothing here or on the feature's own page fixes the problem, use Help → File an Issue.... It builds a support bundle and opens a pre-filled GitHub bug report. See Support and Logging for which log categories to turn on first.

Reference​

File locations​

LinuxmacOSWindows
Settings (AetherSDR.db)~/.config/AetherSDR/~/Library/Preferences/AetherSDR/%LOCALAPPDATA%\AetherSDR\
Logs~/.config/AetherSDR/logs/~/Library/Preferences/AetherSDR/logs/%LOCALAPPDATA%\AetherSDR\logs\

Each launch writes a new timestamped log; attach the newest one. See Support and Logging and Settings and Backups.

By feature​

These pages have their own Troubleshooting section:

See also​