Troubleshooting

Troubleshooting

If your problem is panel-specific (PureSignal, CFC, AGC, etc.) check that panel's wiki page first — many of those have a Troubleshooting section of their own. This page collects general issues that don't fit any single panel.

Known quirks

TUN carrier looks momentarily wide / pulses for ~1 s on the OpenHPSDR Zeus panadapter when first keyed

This is an OpenHPSDR Zeus display artifact — the actual RF transmitted is a clean zero-beat single-tone carrier, verified via an external receiver (KiwiSDR). To be cleaned up at a later date.

Missing native WDSP library on Windows or Linux

If you see errors related to wisdom file generation or missing wdsp.dll / libwdsp.so:

Windows

The native DLLs are automatically built via GitHub Actions.

• Check if Zeus.Dsp/runtimes/win-x64/native/wdsp.dll (or win-arm64) exists.
• If missing, trigger a build: Go to repository Actions → "Build Native WDSP Libraries" → "Run workflow".
• Or build locally following instructions in native/README.md.

Linux

Released tarball — DllNotFoundException running ./Zeus.Server directly

If you extracted zeus-X.Y.Z-linux-x64.tar.gz and ran ./Zeus.Server directly (e.g. on a headless server) and got:

System.DllNotFoundException: Unable to load shared library 'wdsp' or one of its dependencies.
  /…/zeus-X.Y.Z-linux-x64/wdsp.so: cannot open shared object file: No such file or directory
  /…/zeus-X.Y.Z-linux-x64/libwdsp.so: cannot open shared object file: No such file or directory

…the library is in the tarball — it's at runtimes/linux-x64/native/libwdsp.so (alongside libfftw3.so.3 and libfftw3f.so.3). Linux just doesn't search the executable's directory by default.

Fix one of two ways:

1. Use the bundled wrapper, which sets LD_LIBRARY_PATH for you:

   ./zeus                                          # opens browser
   ASPNETCORE_URLS=http://0.0.0.0:6060 ./zeus      # bind all interfaces (server mode)

2. Or export LD_LIBRARY_PATH yourself before invoking Zeus.Server:

   LD_LIBRARY_PATH="$PWD/runtimes/linux-x64/native:$LD_LIBRARY_PATH" \
       ./Zeus.Server --urls http://0.0.0.0:6060

For systemd, set Environment=LD_LIBRARY_PATH=/opt/zeus/runtimes/linux-x64/native in the unit file — see Installation → Linux server for a complete example. On arm64 boxes, swap linux-x64 for linux-arm64.

Building from source

• Check if Zeus.Dsp/runtimes/linux-x64/native/libwdsp.so (or linux-arm64) exists.
• If missing, run ./native/build.sh from the repository root.
• Or wait for the automated GitHub Actions build.

Fallback to synthetic DSP

If native libraries are unavailable, OpenHPSDR Zeus falls back to a synthetic DSP engine. Most UI features work, but actual signal processing requires the WDSP native library.

See native/README.md for detailed build instructions and docs/lessons/wdsp-init-gotchas.md for WDSP-specific troubleshooting.

First-run WDSP wisdom

On first launch on a machine, WDSP/FFTW builds a one-shot "wisdom" cache that takes 1–3 minutes. Don't click Discover or Connect until you see wdsp.wisdom ready result=1 (built) in the console — connecting earlier crashes the backend with a native double-free.

Full detail in Installation → First run.