Summary

After running a library scan on a large ebook library with nested/irregular folders, BookOrbit can mark real book records as missing even though their book_files rows still point at files that exist on disk.

This also causes a notification storm during the scan: repeated Books unavailable / Books restored messages, even though the final scan summary may only report a small missing_count.

Observed behavior

A scan produced many notifications such as:

• Books unavailable: 29 books are no longer available on disk
• Books restored: 25 books were restored on disk
• Books unavailable: 14 books are no longer available on disk

But the final scan job summary was only:

added_count=5
updated_count=218
missing_count=1

The UI then displayed several orange MISSING cards.

Concrete example

BookOrbit DB rows were marked missing:

book_id=7632
status=missing
folder_path=/books/Rising Queen (Court of the Sea Fae Trilogy Book 3) (2020)/City of Thorns (2021)
title=City of Thorns

book_id=7638
status=missing
folder_path=/books/Rising Queen (Court of the Sea Fae Trilogy Book 3) (2020)/Garden of Serpents (2022)
title=Garden of Serpents: The Demon Queen Trials—Book Three

But the files still existed at those paths:

/books/Rising Queen (Court of the Sea Fae Trilogy Book 3) (2020)/City of Thorns (2021)/City of Thorns - C.N. Crawford.epub
/books/Rising Queen (Court of the Sea Fae Trilogy Book 3) (2020)/Garden of Serpents (2022)/Garden of Serpents - C.N. Crawford.epub

The book_files rows also still pointed to the existing files:

book_id=7632
rel_path=Rising Queen (Court of the Sea Fae Trilogy Book 3) (2020)/City of Thorns (2021)/City of Thorns - C.N. Crawford.epub
format=epub

book_id=7638
rel_path=Rising Queen (Court of the Sea Fae Trilogy Book 3) (2020)/Garden of Serpents (2022)/Garden of Serpents - C.N. Crawford.epub
format=epub

Relevant scanner log pattern

The scan logs around these notifications show lots of reconciliation actions like:

action=reuse_moved_book - reused existing book for moved folder
action=drain_virtual_siblings - virtual siblings drained
action=merge_stem_split - stem-split books merged

So this appears to happen when the scanner processes nested or messy folders and collapses/merges records. Some child book records are left with status=missing even though their primary file still exists.

Expected behavior

If a book record has book_files and those files still exist on disk, the scanner should not mark the book as missing merely because folder reconciliation/merge logic handled a parent or sibling folder.

At minimum, before marking a book as missing, the scanner should verify whether the record’s known file paths still exist.

Impact

• UI shows MISSING badges for books that are actually on disk.
• Notifications become noisy and misleading during scans.
• Large legacy libraries with nested folders are hard to trust after scans.

Environment

• BookOrbit running in Docker on macOS
• Library mounted at /books
• Large imported ebook library, roughly 7k-10k records
• Folder structure includes nested/legacy paths rather than consistently normalized Author / Title (Year) / file layout