tsiry-sandratraina.com
A modern, network-enabled music player platform built on Rockbox technology.
rockboxd.tsiry-sandratraina.com
rust
deno
navidrome
airplay
libadwaita
zig
mpris
snapcast
mpd
rockbox
audio
subsonic
1---
2title: "Troubleshooting"
3description: "Common errors, the symptoms they produce, and how to fix them."
4icon: 'wrench'
5---
6
7## No audio when using built-in CPAL on macOS
8
9**Symptom:** `rockboxd` starts cleanly, the UI shows playback progressing,
10but no audio is heard.
11
12**Cause:** the CPAL audio stream failed to open, usually because the selected
13output device was disconnected or the system audio stack returned an error.
14
15**Fix:** update to the latest release. Verify the correct output device is
16set in System Settings › Sound › Output. If you build from source, check that
17the CPAL-based sink compiled correctly (`nm zig/zig-out/bin/rockboxd | grep pcm_cpal`).
18
19## Snapcast: silence, then snapserver disconnects
20
21**Symptom:** snapserver logs `Stream: 'default' eof` shortly after rockboxd starts.
22
23**Cause:** snapserver was started **before** rockboxd, so it opened the
24FIFO first and saw EOF.
25
26**Fix:** start rockboxd first, then snapserver. Rockbox holds a permanent
27write-side handle on the FIFO so snapserver never sees EOF mid-track.
28
29For TCP mode, the order is reversed — start snapserver first.
30
31## Squeezelite disconnects every 36 seconds
32
33**Cause:** the `STMt` heartbeat is not being answered. squeezelite has a
3436-second watchdog.
35
36**Fix:** every `STMt` heartbeat must be answered with `audg`. This is
37already the case in current builds; if you're hacking on
38`crates/slim/`, don't strip that response.
39
40## Stale binary after editing C or Rust
41
42**Symptom:** behaviour doesn't match the source code; logs reference
43old strings.
44
45**Cause:** Zig only re-links when the static libraries are newer than
46the binary.
47
48**Fix:**
49
50```sh
51ls -la zig/zig-out/bin/rockboxd \
52 build-lib/libfirmware.a \
53 target/release/librockbox_cli.a
54```
55
56If `rockboxd` is newer than every `.a`, force a rebuild:
57
58```sh
59# After C changes
60cd build-lib && make lib && cd .. && cd zig && zig build
61
62# After Rust changes
63cargo build --release -p rockbox-cli -p rockbox-server && cd zig && zig build
64```
65
66## "library_directory is not set" after fresh install
67
68**Cause:** `~/.config/rockbox.org/settings.toml` is missing or has no
69`music_dir` key.
70
71**Fix:**
72
73```toml
74music_dir = "/path/to/your/Music"
75```
76
77## AirPlay receiver refuses to connect
78
79**Symptom:** logs show `RTSP ANNOUNCE → 401` or `Receiver requires
80password`.
81
82**Cause:** the receiver requires a PIN/password (most "AirPlay 2" gear).
83
84**Status:** AirPlay 2 pairing/encryption isn't implemented. Use a
85shairport-sync receiver, an Apple TV, an Airport Express, or another
86AirPlay 1 device. See [AirPlay](/audio-output/airplay).
87
88## Chromecast plays once then stops
89
90**Symptom:** first track plays through, queue advances, second track
91gets stuck buffering.
92
93**Cause:** the Chromecast cannot reach back to port 7881 on rockboxd's
94host. Common when rockboxd is in a VM/container.
95
96**Fix:** forward port 7881 to the host, or run the container with
97`--network host`. See the [Chromecast](/audio-output/chromecast) page.
98
99## mDNS discovery returns nothing
100
101**Symptom:** the device picker is empty, even though receivers are on
102the LAN.
103
104**Causes & fixes:**
105
106- **Multicast doesn't cross Docker bridges.** Use `--network host`.
107- **Some Wi-Fi APs filter multicast.** Enable "multicast forwarding" or
108 "IGMP snooping" — vendor-specific naming.
109- **Avahi/mDNS not running.** On Linux, ensure `avahi-daemon` is
110 running for SSDP/Bonjour to work.
111
112## "address already in use" on startup
113
114**Cause:** a previous rockboxd process didn't shut down cleanly, or
115another service is on one of the API ports.
116
117**Fix:**
118
119```sh
120lsof -i :6061 -i :6062 -i :6063 -i :6600
121kill -9 <pid>
122```
123
124…or change the bind ports via the env vars in
125[Reference › Ports](/reference/ports).
126
127## Logs are too quiet
128
129```sh
130RUST_LOG=debug rockboxd
131```
132
133Or scoped:
134
135```sh
136RUST_LOG=rockbox_airplay=debug,info rockboxd
137RUST_LOG=rockbox_slim=debug,info rockboxd
138```
139
140Never use `eprintln!` / `println!` in the codebase — they bypass the
141filter and pollute stdout (which breaks FIFO mode). All Rust logging
142goes through `tracing`.