Skip to content

Troubleshooting

A lane will not start

  1. Check the lane-local error and route decision.
  2. Confirm the route covers the operator RF and is VERIFIED=yes.
  3. Check sdr-demandctl status and the serial-specific service journal.
  4. Confirm another lane/client does not own the physical receiver.
  5. Use public demand ports, never private backend ports.
sdr-demandctl status
systemctl status 'rtl_tcp@SERIAL.service'
journalctl -u 'rtl_tcp@SERIAL.service' --since '-5 minutes'

UI or control will not connect

Inspect public identity and the gateway without restarting anything:

rfsentry-config show
systemctl status rfsentry-api.service --no-pager
journalctl -u rfsentry-api.service --since '-5 minutes' --no-pager

Use the configured API hostname/port, normal certificate validation and a configured UI origin. An alias must satisfy both SAN coverage and allowed origins. The browser's origin includes the API port; it is not changed to the IQ port just because streaming uses that port. Static page success does not prove control authorization, IQ binding or receiver acquisition.

If the browser asks you to sign in, use an rfSentry account on that appliance. Account & access controls the effective browser sign-in policy, initially seeded from AUTH_ENABLED. Origin checks apply even with local access enabled. Machine credentials have separate grants. See browser accounts and source access.

Control connects but IQ does not

Use the discovery and binding sequence to identify the failed stage rather than assuming the decoder is at fault:

Stage What to check
Endpoint discovery fails stream.endpoint must supply a different valid port, correct WSS scheme, /ws/iq and rfsentry-iq-v1; the client keeps the validated hostname.
IQ socket fails to open Reachability of the configured stream port, certificate trust/SANs and the authorized UI origin. Ordinary HTTP on that port returns 404 by design.
Socket opens but no valid frames arrive The worker sent stream.bind with the current session's iqToken, not the operator token. Check lane error, session.ready, receiver fault and quarantine state; socket-open is not a bind acknowledgement.
A working stream closes Inspect control/session closure, receiver faults and slow-client evidence. The gateway closes invalid/unbound IQ connections or persistently overflowing bound connections; do not assume QoS or RF loss without evidence.

An IQ-only disconnect releases its bound session. A surviving control peer can request a new session/token without resetting another lane; reconnecting control repeats auth/discovery. Never retry a released token, silently fall back to API-port IQ, open a second receiver connection, or clear origin storage to fix an endpoint problem. Port/TLS activation needs a deliberate gateway restart; QoS profile-only changes do not require restarting reception.

Streams connect but continuity is poor

Compare IQ sequence/sample counters and Gap/Overflow flags with retune/settings boundaries. A completed block's monotonic stamp is not acquisition UTC, and a gateway-wide control eventSequence gap is not lost IQ. The bounded gateway queue drops whole frames on overflow; independent browser consumers can also fall behind. Keep those losses distinct from RF protocol CRC/FEC errors and display-frame pacing. See queueing/release and the time contract.

sudo rfsentry-qos status reports configured/applied priority and counters, not sample continuity or measured over-the-air WMM. Packet verification and live acquisition tests are separate operator-directed procedures; do not run them automatically while diagnosing a presentation issue.

Start Decoder appears unavailable

Read the preflight reason. Compare lane domain/rate/bandwidth/UTC uncertainty with the generated manifest reference. Changing only the VFO cannot turn a 1.024 MS/s capture into the 2.4 MS/s input required by ADS-B.

Auto Start waits forever

The recommendation should appear immediately from inexpensive priors. A strong exclusive-frequency candidate can run a short decoder trial. Check that the candidate bridge receives IQ, manifest geometry matches, timers advance, and validated output reaches the manager. Manual success with identical geometry usually points to recommendation/trial state rather than the decoder.

Center spike

Record hardware center, VFO, physical LO/driver offset state, gain/AGC, raw complex mean, RMS, and fixed-scale spectrum. Toggle software correction and inspect newly arriving rows. Old waterfall rows do not travel back in time to accept the new setting.

Distinguish constant IQ bias from a nearby tone or broad center artifact. Offset tuning moves the artifact relative to wanted RF; it does not eliminate its source. Enable only when the tuner/driver supports it and the complete signal remains inside usable bandwidth.

Decoder works but UI is slow

Compare worker-side DSP rate with displayed frame rate. Look for full-history queries, root React updates per event, full map collection rebuilds, or hidden surfaces doing presentation work. Do not "fix" this by lowering waterfall quality or discarding evidence.

Browser memory grows

Account for workers, WASM, decoded images, canvases, ImageBitmaps, Blob URLs, GPU buffers, OPFS staging, FCC mode, aviation pages, and DVR hot RAM. The JS heap gauge is neither total process memory nor a permission slip to retain everything forever.

Look for repeated derivative identities, abandoned jobs repopulating caches, unreleased object URLs/surfaces, duplicate buffer copies, and overlapping heavy jobs. Preserve originals/native quality; fix lifecycle and scheduling first.

Failure boundaries and safety contract

Current gateway queues drop complete oldest IQ frames on overflow, mark newly enqueued frames Gap/Overflow and close a persistently slow IQ client. Sequence and sample-counter jumps identify the actual lost range; queued older frames may be sent before the flagged replacement. The receiver reader continues draining its stream; bounded browser sinks report independent loss. Closing control releases only that peer's sessions. Normal route grace, receiver idle and deep-idle deadlines are different phases, not one hardcoded 30-second timer. See release.

Module jobs expose fault/status and manifested retry/output limits; explicit Retry is bounded. A worker wall-time callback is not proof that a synchronous WASM hang can be preempted. Preserve the broader fault/isolation test contract rather than treating a timer or manifest declaration as completed acceptance. Shared retained intelligence/archive workers are not active protocol decoder jobs and may remain available for browsing after reception stops.

Source anchors: gateway src/receiver.c / src/server.c; browser src/api/RfsentryClient.ts, src/dsp/DspPipeline.ts, src/decoder/DecoderManager.ts, decoder.worker.ts and src/detection/activation.ts. Paths belong to their corresponding components. These are inspected paths, not newly performed disconnect/crash/RF tests.

The original required failure behaviors below remain acceptance obligations. An optional wait/fallback or rollback policy must not be described as a proved automatic recovery mechanism without the corresponding evidence. Never steal a busy receiver, reset unrelated origin storage or restart acquisition merely to diagnose a presentation fault.

Browser or Network Falls Behind

  • Keep fixed-size queues.
  • Continue draining rtl_tcp rather than allowing unbounded buffering.
  • Drop whole IQ frames when necessary.
  • Report sequence gaps to DSP and decoders.
  • Reset stateful decoder synchronization when a gap invalidates it.

Browser Disconnects or Crashes

  • Close the public demand connection.
  • Stop all decoder workers for that session.
  • Allow sdr-demandd to perform its normal idle deadline and clean shutdown.

Existing SDR++ Client Is Active

  • Return a clear receiver busy state.
  • Do not interrupt the existing client.
  • Optionally allow the UI to wait for availability without creating journal spam.

Receiver Disappears

  • Surface the exact alias and serial in the UI.
  • Preserve other receiver sessions.
  • Let the existing serial-aware supervisor and demand manager own recovery.
  • Avoid a rapid reconnect loop from the browser.

Decoder Hangs or Crashes

  • Bound worker runtime, memory, and output.
  • Restart only on explicit demand with bounded retry.
  • Keep the core tuner and audio operational.
  • Show decoder failure separately from receiver failure.

Low-Confidence Classification

  • Keep the current manual mode or offer ranked alternatives.
  • Never force a high-impact retune based on weak evidence.
  • Preserve an explicit unknown result.

Intelligent Activation Cannot Converge

  • Keep the signal selected and explain which setting could not be resolved.
  • Apply only evidence-supported, unpinned changes; never manufacture a mode or decoder result to complete the workflow.
  • If staged gain or DSP refinement worsens clipping, headroom, or SNR, revert that stage automatically and retain the previous measurement.
  • If the signal disappears, the receiver becomes busy, or route ownership changes during activation, cancel safely and offer the complete undo snapshot without disturbing another consumer.
  • An unavailable or failed decoder leaves the receiver tuned and listening, with decoder failure reported separately from signal-path health.

Encrypted or Unsupported Signals

  • Identify the modulation or protocol where possible.
  • Display encryption or incompatibility state.
  • Do not imply that content can be decoded.

Idle Behavior

  • Opening the static UI must not wake a receiver.
  • A receiver with no manual, scan, or decoder consumers must be released after its configured short route grace so sdr-demandd can start its normal idle deadline.
  • Other active receiver lanes must remain connected when one lane is released.
  • No decoder worker remains resident without a session.
  • No new fast timer or polling loop should run continuously on the Pi.
  • Logging should be state-change-driven rather than per-frame or per-poll.

Documentation does not open

rfsentry-config show
find /usr/local/share/rfsentry-web/docs -maxdepth 2 -type f | head
journalctl -u rfsentry-api.service --since '-5 minutes'

Request /docs/ on the configured API HTTPS origin with normal certificate trust, not an assumed loopback name or the IQ listener. The docs are static files; there is no MkDocs runtime daemon to restart. On the correct listener, a 404 can mean the docs build was absent from installed dist; a script/CSP error points to the docs-specific static headers or missing local asset.