Diagnose a missing audio device

A red audio device unavailable banner appeared in BanterLab, and the run is refusing to start (or has paused mid-run). This guide explains what triggered it and how to recover.

In bahn, a missing output device shows as a red light beside the lane's Device button in the mixer. The lane keeps your choice and plays again when the card is back. The other lanes and the song are not affected. See Send two mixes to two cards.

What it means

The TX or RX node's stored output / input device name does not resolve to any audio device currently visible on this host. Either:

  • the device was never present at startup (a stored device name from a previous session or a different machine), in which case the pre-run gate refuses to start the test; or
  • the device was unplugged mid-run, in which case the iter scheduler is paused and waiting for the device to come back.

In both cases the banner names the offending direction (output, input, or both) and the requested device name. Iters do not silently freeze any more — they're explicitly refused or paused, the banner tells you so, and they resume the moment the device returns.

The two cases

Case When Banner Iter scheduler
Pre-run startup or before pressing Run red AUDIO DEVICE UNAVAILABLE refused to start (aborted("DEVICE_MISSING") in the log)
Mid-run USB unplug during a run red AUDIO DEVICE UNAVAILABLE paused; resumes on replug

For the related "OS audio subsystem unresponsive" red banner — where the device IS present but the OS audio server is not delivering samples — see diagnose-audio-unhealthy-banner instead. The current spec distinguishes the two cases by reason code (DEVICE_MISSING vs POST_GIVEUP_TIMEOUT).

Recovery steps

Try in order. Each step is non-destructive; stop as soon as the banner clears.

  1. Confirm the device is gone. Run:

    pactl list short sinks
pactl list short sources

    The requested device should be absent. If it IS listed but the banner is up anyway, that's a different failure mode — jump to diagnose-audio-unhealthy-banner.

  2. Replug the USB audio adapter. Wait 2 s, replug. Re-run pactl list short sinks. Once the device reappears, the banner clears within one DeviceManager tick (≤ 1 s). For a mid-run case the iter scheduler also resumes automatically and arms a fresh inter-iter gap.

  3. Pick a different device. If the device is permanently gone — settings copied from another machine, or a rig change — open the per-direction Out / In button on the node and choose an available device (or the bus sentinel for loopback testing, or off to disable that direction). Re-run.

  4. Edit the test spec. Multi-row test sets can carry a nodes.outputDevice / nodes.inputDevice value per node. Open the spec file and change it to either a device that's actually present, bus, or off.

  5. For a stuck PipeWire — see step 4 of diagnose-audio-unhealthy-banner. If pactl list short sinks keeps not showing a device that's physically plugged in, the audio server itself is the problem, not BanterLab.

What does NOT trigger this banner

  • The bus and off route sentinels. These are first-class operator choices; they never require a hardware device, and the gate / mid-run detector treat them as always-ready.
  • A device whose name is partially matched. DeviceManager::findAudioOutput uses fuzzy matching — a USB device whose PipeWire id changed slightly across replugs still resolves.
  • A device that's present but whose codec format doesn't match. That is a different failure mode and out of scope; the gate only checks presence, not format compatibility.

Multi-row test sets

When a queued test set hits a row whose TX or RX device is missing, the row is recorded as skipped (with reason DEVICE_MISSING) and the runner advances to the next row. The whole set does not abort — operator-driven device choices can vary per row. The log includes a ⚠ Test '<row name>' skipped: required audio device missing. line for each skipped row.

Reference

In this section