> ## Documentation Index
> Fetch the complete documentation index at: https://rockboxzig.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common errors, the symptoms they produce, and how to fix them.

## No audio when using built-in CPAL on macOS

**Symptom:** `rockboxd` starts cleanly, the UI shows playback progressing,
but no audio is heard.

**Cause:** the CPAL audio stream failed to open, usually because the selected
output device was disconnected or the system audio stack returned an error.

**Fix:** update to the latest release. Verify the correct output device is
set in System Settings › Sound › Output. If you build from source, check that
the CPAL-based sink compiled correctly (`nm zig/zig-out/bin/rockboxd | grep pcm_cpal`).

## Snapcast: silence, then snapserver disconnects

**Symptom:** snapserver logs `Stream: 'default' eof` shortly after rockboxd starts.

**Cause:** snapserver was started **before** rockboxd, so it opened the
FIFO first and saw EOF.

**Fix:** start rockboxd first, then snapserver. Rockbox holds a permanent
write-side handle on the FIFO so snapserver never sees EOF mid-track.

For TCP mode, the order is reversed — start snapserver first.

## Squeezelite disconnects every 36 seconds

**Cause:** the `STMt` heartbeat is not being answered. squeezelite has a
36-second watchdog.

**Fix:** every `STMt` heartbeat must be answered with `audg`. This is
already the case in current builds; if you're hacking on
`crates/slim/`, don't strip that response.

## Stale binary after editing C or Rust

**Symptom:** behaviour doesn't match the source code; logs reference
old strings.

**Cause:** Zig only re-links when the static libraries are newer than
the binary.

**Fix:**

```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
ls -la zig/zig-out/bin/rockboxd \
       build-lib/libfirmware.a \
       target/release/librockbox_cli.a
```

If `rockboxd` is newer than every `.a`, force a rebuild:

```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
# After C changes
cd build-lib && make lib && cd .. && cd zig && zig build

# After Rust changes
cargo build --release -p rockbox-cli -p rockbox-server && cd zig && zig build
```

## "library\_directory is not set" after fresh install

**Cause:** `~/.config/rockbox.org/settings.toml` is missing or has no
`music_dir` key.

**Fix:**

```toml theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
music_dir = "/path/to/your/Music"
```

## AirPlay receiver refuses to connect

**Symptom:** logs show `RTSP ANNOUNCE → 401` or `Receiver requires
password`.

**Cause:** the receiver requires a PIN/password (most "AirPlay 2" gear).

**Status:** AirPlay 2 pairing/encryption isn't implemented. Use a
shairport-sync receiver, an Apple TV, an Airport Express, or another
AirPlay 1 device. See [AirPlay](/audio-output/airplay).

## Chromecast plays once then stops

**Symptom:** first track plays through, queue advances, second track
gets stuck buffering.

**Cause:** the Chromecast cannot reach back to port 7881 on rockboxd's
host. Common when rockboxd is in a VM/container.

**Fix:** forward port 7881 to the host, or run the container with
`--network host`. See the [Chromecast](/audio-output/chromecast) page.

## mDNS discovery returns nothing

**Symptom:** the device picker is empty, even though receivers are on
the LAN.

**Causes & fixes:**

* **Multicast doesn't cross Docker bridges.** Use `--network host`.
* **Some Wi-Fi APs filter multicast.** Enable "multicast forwarding" or
  "IGMP snooping" — vendor-specific naming.
* **Avahi/mDNS not running.** On Linux, ensure `avahi-daemon` is
  running for SSDP/Bonjour to work.

## "address already in use" on startup

**Cause:** a previous rockboxd process didn't shut down cleanly, or
another service is on one of the API ports.

**Fix:**

```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
lsof -i :6061 -i :6062 -i :6063 -i :6600
kill -9 <pid>
```

…or change the bind ports via the env vars in
[Reference › Ports](/reference/ports).

## Logs are too quiet

```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
RUST_LOG=debug rockboxd
```

Or scoped:

```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
RUST_LOG=rockbox_airplay=debug,info rockboxd
RUST_LOG=rockbox_slim=debug,info   rockboxd
```

Never use `eprintln!` / `println!` in the codebase — they bypass the
filter and pollute stdout (which breaks FIFO mode). All Rust logging
goes through `tracing`.