Troubleshooting — xng docs

When nothing decodes, it is almost always one of a handful of things — the radio, the sample rate, the gain, or the antenna. Here is how to find out which.

Start with the built-ins

Before changing anything, let xng tell you what it sees:

bash

xng devices      # is the radio detected at all?
xng selftest     # is the decode pipeline itself healthy?
xng iq-info capture.cf32 -r 2000000 -c 131500000   # is there signal in a recording?

“xng devices shows nothing”

The SDR driver is missing or the device is not reachable.

SoapySDR module

Install the vendor module — e.g. soapysdr-module-all, or the RTL-SDR / Airspy / SDRplay package for your distro.

USB permissions

On Linux, add the udev rules for your dongle and re-plug it, or test as root to confirm it is a permissions issue.

Native vs Soapy

If a native Airspy build does not see the device, try backend=soapy in the driver string, or vice-versa.

“It runs but never decodes”

The single most common cause: the sample rate is not an integer multiple of the mode’s channel rate. If a session loads cleanly but produces nothing, this is the first thing to check. The easiest fix is to omit --sample-rate /--channels entirely and let the mode’s built-in plan choose them.

Gain

Too low and there is nothing to decode; too high and the front end overloads. Run xng survey --tune-gain to find the sweet spot, or drop --gain for AGC.

Center frequency

Make sure your channels actually fall within the captured bandwidth around --center-freq.

Antenna / band

L-band modes (Aero, STD-C, Iridium) need a patch antenna and an LNA — a VHF whip will hear nothing there. See Inputs & outputs.

Is anything on the air?

HF and satellite traffic is intermittent. Use xng survey to soak a band and confirm there is something to hear before blaming the setup.

“A config key is rejected”

Station files are validated strictly — an unknown key is a hard error, not a silent no-op. Check the spelling against the configuration reference; a rejected key usually means a typo or a value in the wrong block.

Decoding less than the old tool

If you are comparing against dumphfdl, dumpvdl2, or AIS-catcher, first switch effort up:

bash

xng listen --sdr driver=rtlsdr --mode hfdl --demod-effort max ...

live is tuned to stay real-time on a Raspberry Pi; max trades CPU for the last few percent of frames. On the published benchmarks xng is competitive with or ahead of the reference tools, so a large gap usually points at gain, antenna, or rate.

Still stuck?

Reproduce it with -vv for more detail, capture a short IQ file so the problem is replayable, and open an issue on GitHub. A recording plus the exact command line is the fastest path to a fix.