One Song Wouldn't Play. 231 Files Were Broken. Lidarr's Ogg Tag Writer Was the Culprit.
Vicente Louvet
- 7 minutes read - 1412 wordsOn September 11, 2026, one song would not play. The client just retried it, in a loop, forever. Not a silence, not an error dialog — a little spinner that never resolved. I’d seen that behavior before, and I’d always blamed the server. This time the server was fine, and the truth was stranger: Lidarr had been quietly corrupting my Ogg Vorbis files for months, nightly, one byte at a time.
The setup is a normal homelab. Music lives on the NAS (.12, ZFS) and is served by Navidrome on .21, which streams the raw file — transcoding is off — to a desktop client called Supersonic. Lidarr 3.1.0.4875, also on .21, manages the library. Somewhere along the way I’d set “Write Metadata to Audio Files” to Sync (writeaudiotags = Sync, scrubaudiotags = True), which means every nightly Refresh Artist rewrites tags and embeds cover art directly into the files themselves.
That setting is the whole story. It turned a metadata tool into a corruption machine.
The symptom #
The song wouldn’t play in Supersonic; the client retried it in a loop. ffmpeg and mpv on the file both said the same thing:
Invalid Setup header
Because Navidrome streams the raw file, the server was healthy — it was hand-delivering an unplayable file to the client. When your server streams raw files, a player that retries forever is a file problem, not a server problem. That one sentence saved me most of the afternoon.
The file was broken. But it was one file, and I’d been meaning to fix my tagging workflow anyway. Then I looked at the Lidarr logs and found the pattern that turned a one-off into a project.
The byte #
An Ogg stream is a sequence of pages. Each page header carries a segment table of lacing values: a value of 255 means “this packet continues into the next segment,” and any value below 255 ends the packet. A header flag (0x01, “continued”) on a page says its first packet is a continuation of the previous page’s last one.
When Lidarr’s Ogg writer rewrote the Vorbis header pages — and the comment header grows when you embed cover art — it appended a spurious 0 lacing value after a 255 at the end of a header page, while still flagging the next page as “continued.” A 255, 0 pair says “the packet continues… and ends here with zero bytes.” The Vorbis setup header is therefore declared finished one page early, and the next page claims to continue a packet that already ended. Decoders reject the setup header, and the file is unplayable — even though every audio byte is intact.
So the audio was perfect. The header was lying. And the fix was a single byte per page.
The logs made the scope obvious. Every Lidarr Ogg tag write in its logs, 45 of 45, produced a broken file. mp3, m4a, and flac writes were fine. Only Ogg Vorbis, every single time.
How many files #
I’d been running this setup for months. Time to count the damage.
.ogg files in the affected share | 825 |
| broken | 231 across 19 albums |
| file mtimes of the broken set | 2026-05-25 to 2026-09-10 (still happening nightly) |
| detector matches | 231 of 231 broken, 0 false positives among the 594 healthy |
| stray bytes per file | 155 files had 1, 29 had 2, 22 had 3 |
The mtimes are the damning part. The newest broken file was stamped 2026-09-10 — the night before I found it. This wasn’t a one-time bad run from May. Lidarr had been re-breaking files on every nightly Refresh Artist for months, and I’d been re-ripping nothing, because nothing had looked wrong.
One red herring worth naming, because it’s the kind of thing that wastes an hour if you don’t check whether the file actually fails to play: 17 mp3s from one soundtrack showed Header missing in the same sweep. That was a separate 2024 issue, still decodable, completely unrelated to this bug. If I’d chased it I’d have burned the afternoon on a phantom. The rule I now use: a scan warning is a lead, not a verdict — confirm the file actually fails to play before you treat it as broken.
The detector and the repair #
I did not want to guess. I wanted a detector with a measured false-positive rate before I touched a single file.
- Detector: walk the Ogg pages; flag a header page whose segment table ends
[..., 255, 0]and whose following page has the continuation flag set. That pattern was exact on this library — 231 of 231 broken files matched, and 0 of the 594 healthy files did. Zero false positives. That’s the number that made the repair safe to run in place. - Repair: a small Python script,
oggfix.py, drops every such0in the header region and recomputes the page CRC. You can’t just delete a byte here — Ogg pages are CRC-32 checked, with a non-standard polynomial, so a naive delete corrupts the page and the file gets more broken. The script fixes the byte and repairs the checksum.
The first version of the repair removed only the first bogus zero, and it failed on an album that had three. Lesson: assume the fault repeats within a file. The fix had to clear every stray 0 in the header region, not just the first one it found.
# in outline; the real script also fixes the segment count in the page header
for page in header_pages:
table = page.segment_table
while len(table) >= 2 and table[-2] == 255 and table[-1] == 0:
table.pop() # drop the trailing spurious 0
page.crc = crc32(page) # Ogg CRC-32, non-standard polynomial
The wrapper, apply_fix.sh, copies the originals to a dated backup directory on the pool before touching anything. The NAS keeps no ZFS snapshots of the media dataset, so that backup directory was the only undo. Keep an undo path when the filesystem does not give you one.
After the in-place repair I rescanned all 825 files: 0 with the pattern and 0 ffprobe errors, and the original song streamed normally. Lidarr’s setting is now Never — any other mode re-breaks every Ogg it retags, guaranteed. I have not filed this upstream yet.
Three traps #
These cost me real time, and each one is a different flavor of “the tool ate your input.”
ffmpeg reads stdin. Inside a while read f; do ffmpeg -i "$f" …; done < list.txt loop, ffmpeg eats the rest of the file list, so paths arrive truncated and most files are silently skipped. My dry run used xargs and passed; the real run used while read and did not. The fix is boring and mandatory: ffmpeg -nostdin … </dev/null in any loop.
pkill -f "pattern" over ssh matches its own command line and kills your session. The bracket trick exists for exactly this: pgrep -f "[p]attern", then kill the PID. And a pattern containing {} is a regex error, so pkill silently kills nothing — no error, no match, no kill, just nothing.
Clocks. Lidarr’s logs are in local time (America/Denver); the NAS stamps mtimes in UTC. Lining up “which nightly run broke which file” needs the 6-hour shift: 21:29 MDT is 03:29 UTC. Misread that and every correlation is off by a day.
Takeaways #
- A player that retries forever is a file problem, not a server problem when the server streams raw files. Confirm the server is healthy before you debug it.
- When a tool writes into your originals nightly, it has nightly opportunities to be wrong. Prefer sidecar metadata, or keep snapshots. “Write tags to files” is a standing write contract with your library.
- Build the detector first and measure its false-positive rate on the healthy set before repairing anything. 231 of 231 with 0 false positives is what made in-place repair safe.
- Assume a corruption repeats within a file. The first repair fixed one byte and missed the album with three.
- Keep an undo path when the filesystem does not give you one. No ZFS snapshots on the media dataset meant a dated backup directory was the only way back.
- A scan warning is a lead, not a verdict. The 17 “Header missing” mp3s were decodable and unrelated; confirm a file actually fails to play before you chase it.
One byte. In the header. Every Ogg Lidarr touched, every night, for months. The audio was never damaged — only the lie in front of it.