Troubleshooting

Troubleshooting

The usual problems, in the order they tend to happen. Where a detail depends on your system and could not be confirmed it is marked "check".

The radio is not found

1. Check the cable and press Rescan for devices in the source list. The setup wizard says it plainly when it cannot see a radio. If the list shows only the test signal, OnAir shows "No radio found" with a fix button for the likely cause.
2. Try another USB port, directly on the computer and not through a hub, and a shorter cable. USB 3 radios (RX888, fast Fobos rates) need a USB 3 port.
3. The log (onair.log, see below) says which library saw how many radios.

Windows

• A HackRF, RTL-SDR, Airspy, Airspy HF+, Fobos SDR and RX888 MkII need the WinUSB driver, installed once with Zadig. In Zadig turn on List All Devices if the radio is not listed, choose the radio, and install WinUSB.
• The RX888 MkII needs WinUSB for both 04B4:00F3 (boot loader) and 04B4:00F1 (the running radio); replug on a USB 3 port afterwards.
• SDRplay RSPs: install the SDRplay API and make sure the SDRplay API Service is running. OnAir shows a help card when an RSP is plugged in but the API is missing.
• LimeSDR: the Mini needs FTDI's FT60x driver; the LimeSDR-USB needs the Cypress CyUSB3 driver, not WinUSB (do not replace it with Zadig), plus PothosSDR or LimeSuite. See BladeRF, LimeSDR and USRP.
• After a driver change unplug the radio, plug it in again and press Rescan for devices.

macOS

• No driver is needed for most radios. If the radio is missing, replug it and rescan; for SDRplay install the SDRplay API.
• Sound-card style sources and the monitor may trigger a macOS permission prompt for the microphone or audio input. Allow it in System Settings > Privacy and Security (check the exact name on your macOS version).

Linux

• Install the udev rules: run sudo ./install-udev-rules.sh from the OnAir folder (the .deb package does it for you), then unplug and replug the radio. The Copy the udev command button in the help card copies it.
• Airspy: add yourself to plugdev (sudo usermod -aG plugdev $USER), log out and in, and replug.
• On Dragon OS and similar distributions that ship their own SDR libraries, see the build note in Build from source.

Gatekeeper, SmartScreen and antivirus

• macOS: the app is not signed with a developer certificate yet. The first time, right-click OnAir and choose Open. Intel Macs need a processor with AVX2 (2013 or newer).
• Windows: the installer is not code-signed, so Windows may warn about an unknown publisher. Choose "More info" and "Run anyway" only for a file you downloaded from the release page.
• Antivirus programs sometimes flag unsigned SDR software that talks to USB devices and the network. Check that the file came from the release page and, if you want certainty, compare its SHA-256 with SHA256SUMS in the release. If your program quarantines OnAir, add an exception for the OnAir folder (check your program's settings) and report a false positive to the vendor.

Linux libraries

• The .deb carries its own video decoder and does not depend on your system's FFmpeg. Install it with sudo apt install ./onair_<version>_<arch>.deb so dependencies are fetched.
• The portable archive runs from bin/onair; missing libraries show up as an error at start (check with ldd bin/onair). Radio libraries (libusb, libhackrf, SoapySDR modules) come from your distribution.
• SoapyRemote needs the client module (sudo apt install soapysdr-module-remote).

No signal, overload and gain

Look at the ADC line in the status:

• ADC OVERLOAD or "reduce the gain (or enable AGC)": there is too much signal. Lower the gain, add an FM or LTE notch filter, or move the antenna.
• ADC level low or "sees almost nothing - antenna / gain?": raise the gain or check the antenna and cable.
• Auto-tune sets the gain for you. Optimise gain sweeps the radio's gain range, measures the mode's signal-to-noise ratio and keeps the lowest gain within 0.5 dB of the best that does not overload the converter. Undo gain goes back.
• Check the frequency and the standard (DVB, ATSC, DAB). The setup wizard's country picks the right one.
• Strong nearby transmitters can overload a wideband radio even when you tune elsewhere. A filter or a lower gain helps more than a better antenna.

Antenna basics

• Height and a clear view toward the transmitter matter more than anything else.
• Match the antenna to the band: a telescopic whip set to a quarter wave for VHF, a dedicated antenna for 1090 MHz, 1.5 GHz or 2.4 GHz, a long wire or loop for HF.
• A short, good cable beats a long, thin one; keep the radio near the antenna and the computer far away if you can (USB noise).
• Active antennas and LNAs need the Bias-tee. Never switch it on with a passive antenna or a DC short in the path; the tooltip warns about damage.

Crackling or stuttering audio

• Raise Delay (ms) in the monitor's Audio... pop-up if you use Monitor audio.
• Close other programs that use the CPU or the audio device; lower the sample rate or narrow the channel.
• Check that the sound is not coming from two receivers at once: only one plays audio at a time (the speaker button of the tab).
• Windows uses WASAPI through miniaudio, macOS CoreAudio. Try another output device.
• See also "No sound" below.

High CPU and heat

• Lower the sample rate; wide captures need a decent CPU (an Airspy at 10 Msps could not keep up with live ATSC on a 2-core laptop).
• Close extra receivers and unused windows. Reduce CPU when hidden (View menu) lowers the load when the window is not visible.
• LDPC error correction and picture repair run on the GPU where available (Metal on macOS, Direct3D 11 on Windows). On Linux this runs on the CPU. DVB-S / S2 and DTMB have a CPU / GPU / Auto compute setting.

Dropped samples

Hover the dropped indicator in the status bar: it says what is happening.

• Arriving from the radio below 97 % of the set rate / callback gaps: the radio or its driver hands over less than asked. Try a USB port on the computer (no hub), a shorter cable, or a lower sample rate.
• Ring overflow: OnAir did not read the input fast enough. Close other programs, or pick a lower sample rate.
• Receiver load: near 100 % of real time the receiver is just keeping up.
• Network radios: the status bar counts the lost samples (underruns). rtl_tcp uses 8-bit samples up to about 2.5 Msps; a PlutoSDR over USB reaches about 4 Msps. Use a wired network.
• Files and the test signal never lose samples.

Frequency offset (ppm) and the DC spike

• Cheap dongles have a crystal that is off by tens of ppm. RTL-SDR radios list a ppm setting under Radio settings (whole ppm). Tune a signal of known frequency (a broadcast carrier, a time-station carrier) and set the ppm until it sits exactly where it should. For converters use LO correction (ppm): see converters.
• The spike in the middle of the spectrum is the radio's own oscillator leaking in (strong on the HackRF and RTL-SDR). The DC option has Remove (filtered out of the samples), and Tune beside it, where the radio tunes just beside the channel and moves it back digitally (needs a higher sample rate). A line that stays at a round frequency when you retune is interference from the radio's clock, not the DC spike.
• A faint mirror image of every signal on the other side of the centre is an I/Q imbalance: switch on IQ correction.
• The RTL-SDR Blog V4 up-converts HF inside the Blog library; OnAir never switches direct sampling on for it. See RTL-SDR.

No sound

• A mode that plays sound has a speaker or Listen control. HF decoders (FT8, RTTY, CW, PSK31, JS8Call, SSTV) have Listen; the command line is silent unless you add --listen.
• Digital voice (DMR, P25, NXDN, dPMR, D-STAR) needs a codec library, and M17 / FreeDV need codec2: look at the ? next to the sound. See Voice codecs.
• Some sound is not decoded at all: HD Radio (patented), CDR (DRA+, until you install the optional add-on) and Inmarsat Aero voice. OnAir shows stations and data.
• Use Monitor audio to listen to a channel in modes without sound of their own.
• On Linux, sound did not work when OnAir was started with sudo; fixed in 0.2.5.

Android: "App not installed" or the update fails

0.2.7 is signed with a new permanent key, so it cannot be installed over 0.2.6. Uninstall 0.2.6, then install the 0.2.7 APK. Later updates install normally. See Android.

OnAir crashes or does not start

• Crash reports are written to crash.txt next to the log; nothing is uploaded.
• If a start keeps failing, OnAir tries the other interface after one unfinished start and, after two in a row, sets your saved settings aside and starts with the defaults. A note on screen says where the old settings are kept.
• Release 0.2.5 fixed a crash at start on processors without AVX2.
• A broken update: download the installer from the release page and install over it. If GitHub is blocked, see Update mirror.

Where things are

What	Windows	macOS	Linux
Data (recordings, results)	%LOCALAPPDATA%\OnAir	~/Library/Application Support/OnAir	~/.local/share/onair
Settings	%APPDATA%\OnAir\settings.conf	the app's preferences	~/.config/onair/settings.conf
Log and crash report	%APPDATA%\OnAir (onair.log, crash.txt)	~/Library/Logs/OnAir	~/.config/onair

More in Settings and files. DECT2_DATA_DIR points OnAir at another data folder.

How to send a bug report

1. Reproduce the problem once with the receiver running.
2. In the diagnostics strip press Copy diagnostics: it copies the version, system, radios, messages and radio log lines to the clipboard, and the button says Copied. Paste it into your issue.
3. Better, press Save bug report: one zip with diagnostics.txt, the log (onair.log, onair-prev.log) and the last crash report (crash.txt).
4. Open a GitHub issue and attach the zip. Say what you did, what you expected, what happened, your operating system, your radio and the standard of the channel. A short IQ recording of the problem (Record IQ) is the most useful attachment.
5. Questions go to Discord.

Building: the computer freezes

Run cmake --build build -j "$(getconf _NPROCESSORS_ONLN)" (one job per core). A bare -j starts hundreds of compile jobs and can run out of memory.

Related

Getting started | FAQ | Supported radios | Install