A library scan in Audiobookshelf can finish without adding anything and without showing a single error. New books don’t appear in Recently Added, the web UI stays quiet, and adding a different book doesn’t help either. The scan didn’t actually finish, though. It crashed partway through, and the only place that says so is the scan log.

If you open it you’ll see something like this:

[LibraryScanner] Library scan f44346bc-9e5a-4056-8d35-b201fba20c32 failed after 0:04 | 0 Added | 0 Updated | 0 Missing.
SequelizeUniqueConstraintError
  bookId must be unique
  authorId must be unique
  SQLITE_CONSTRAINT: UNIQUE constraint failed: bookAuthors.bookId, bookAuthors.authorId
  sql: 'INSERT INTO `bookAuthors` (`id`,`createdAt`,`bookId`,`authorId`) VALUES ($1,$2,$3,$4);'

0 Added | 0 Updated | 0 Missing is the tell. The scan tried to write a book and hit a database constraint it couldn’t get past.

What’s actually happening

Audiobookshelf keeps the link between a book and its authors in a join table called bookAuthors. That table has a unique constraint on the (bookId, authorId) pair, which means a single book can only be linked to the same author once. Reasonable rule.

The problem is what happens when a scan tries to break it. When Audiobookshelf builds a new book, it goes through the book’s author list and inserts one bookAuthors row per author. If the same author ends up on that list twice, the second insert fails the unique constraint and throws.

Here’s the part that turns a small data problem into “nothing imports anymore”: the scanner doesn’t catch that error per book. One book throws, the exception unwinds the whole scan, and every book the scanner hadn’t reached yet never gets added. That’s why a single malformed book blocks every new book you’re trying to import, even unrelated ones. It also means the count reads 0 Added instead of “added 4, skipped 1.”

So where does the duplicate author come from? Usually one of these:

• A sidecar metadata file in the book’s folder (metadata.json, metadata.opf, or a .nfo) that lists the same author twice.
• Audio file tags where the author appears more than once.
• Two entries that look slightly different to you but resolve to the same author in Audiobookshelf, so they collapse to one authorId.

Audiobookshelf already de-duplicates authors that come from a single source, so a plain Author; Author in one tag is handled. The cases that slip through are the ones where the duplicate spans two sources, or two spellings land on the same author record.

Find the book that’s breaking the scan

The frustrating part is that the error doesn’t name the book. The bookId and authorId in the log are internal IDs, not titles. You have to work backwards.

Read the scan log. Every scan writes a full log to metadata/logs/scans/ (so /metadata/logs/scans/ inside Docker). Open the most recent file. It lists each book as it’s processed. The book logged immediately before the ERROR line is almost always the culprit, because that’s the one the scanner choked on.

If the scan log isn’t detailed enough, turn on debug logging first (Settings > Logs, set the log level to Debug), run the scan again, and watch for the last book processed before the error. That’s the one to inspect.

Fix the duplicate author

Once you know which book it is, check it for a repeated author.

Sidecar files first. Look in the book’s folder for metadata.json, metadata.opf, or a .nfo file. Open it and check the authors list for a literal duplicate or two near-identical names. This is the most common cause, and editing a text file is safer than touching tags.

Then the audio tags. Audiobookshelf reads the author from the ARTIST tag (falling back to ALBUM ARTIST) of the first audio file in the book. Open that file in a tag editor like Mp3tag or Kid3, and make sure the author isn’t listed twice across those fields. If you’d rather not install anything, ffprobe will dump the tags:

ffprobe -hide_banner -show_entries format_tags "your-book.m4b"

Remove the duplicate so the author appears exactly once, then rescan. The book should import, and so should everything that was stuck behind it.

When you can’t find the duplicate

Sometimes the tags and sidecar files look clean and the scan still fails. This is where it gets tedious, and it’s the situation the original report ran into.

The reliable way to identify the book is to look up the IDs from the error in the database. Audiobookshelf stores everything in a SQLite file (absdatabase.sqlite in your config folder). Open it with a viewer like DBeaver, find the bookId from the error in the books table and the authorId in the authors table, and you’ll see exactly which book and author are involved.

If you go this route, work off a backup copy of the database, or stop the server first. Two programs writing to the SQLite file at once can corrupt it. A backup is safer than stopping the server, since you can’t damage your live database by accident. Removing the duplicate bookAuthors row by hand will clear the error, but editing the database directly is a last resort, not something to reach for first.

One thing that gets suggested in the issue thread is moving the book file to the root of your library so it scans in. That sometimes gets the book imported because it changes how the metadata is read, but users found the underlying error keeps firing on the next scan. It’s a way to unstick one book in a pinch, not a fix.

Affected versions

This exact crash was reported and fixed once back in v2.4.0, where the trigger was a duplicate author in a book’s stored metadata. The fix covered that path, but the (bookId, authorId) constraint can still fire in current versions (it’s been hit on v2.35.x) when the duplicate comes from somewhere the de-duplication doesn’t reach. The scanner still aborts the whole run on a single bad book rather than skipping it and moving on, and it still doesn’t log the title that broke, which is the real reason this one is so annoying to track down.

If your books aren’t showing up in SoundLeaf, this is worth ruling out on the server before you go hunting in the app. SoundLeaf only shows what your server actually added to its library, so if a scan died on a duplicate author, no amount of pull-to-refresh will make the book appear. Check the server’s scan log first.

Happy listening, Hemant 🎧