Troubleshooting

Troubleshooting

The dashboard does not start

Check the process directly:

spectrum-alert web --host 0.0.0.0 --port 8000

Common causes:

• Port already in use — choose another port with --port; Docker uses host port 8088 by default.
• Missing web dependencies — reinstall with pip install -e ..
• Wrong working directory in Docker — the image serves package assets, not files from the checkout.

Check the container:

docker compose ps
docker compose logs -f spectrumalert

No RTL-SDR detected

Check the host first:

lsusb | grep 0bda:2838
rtl_test -t

If lsusb shows nothing:

• Reconnect the dongle.
• Try a different USB port or a powered hub.
• Avoid USB 3 ports that have known RTL-SDR compatibility problems.

If rtl_test reports a permission error:

sudo usermod -aG plugdev "$USER"

Then log out and back in.

LIBUSB_ERROR_BUSY or “Resource busy”

A physical dongle can only be open in one process. Stop dashboard monitoring before running a CLI scan on the same receiver, or use a second dongle for a second process.

Check for a stale process:

ps -ef | grep -E "spectrum-alert|rtl_"

Waterfall is blank or the receiver appears wedged

If read_samples hangs while rtl_test -t still reports the device, the dongle is in the known stuck state after an abnormal exit. Reset it:

usbreset 0bda:2838

If usbreset is unavailable, unplug and reconnect the dongle. A reset can change the device path from /dev/bus/usb/001/005 to another number, which is why the Docker configuration maps the whole USB bus rather than one device path.

Data Management is empty

Confirm the dashboard is using the expected working directory. The data directory is relative to where the app was started:

pwd
ls data/features data/anomalies data/spectrum

In Docker, the data directory is mounted from the checkout:

docker compose exec spectrumalert ls /app/data

Training says “No feature data found”

Training needs feature CSVs for the selected mode:

ls data/features/features_*_lite.csv
ls data/features/features_*_full.csv

A model needs at least ten usable feature rows. Generate test data with:

python scripts/generate_iq_samples.py --data-dir /tmp/demo/data

Training succeeds but model status shows “Not deployed”

The model status polls every 30 seconds. Training completion triggers an immediate refresh in current builds. If the panel still looks stale, reload the dashboard or check:

ls models/

A model artifact must exist under models/ in the same working directory as the app.

UI looks stale after an update

Hard-reload the page or rebuild the container:

docker compose build
docker compose up -d

The dashboard assets are served by the backend; a rebuilt image is required for container deployments.

Chart is empty while data exists

The Monitor chart requires a live /api/spectrum response. Feature and anomaly archives populate Analytics and Data Management, not the live spectrum chart. Use the Workspace scan or start monitoring to populate the waterfall.

Related

• Installation
• Docker
• FAQ