Skip to content

Incident Report: 2026-01-26 - Audiobookshelf Scanner Crash / Library "Loss"

Status

Resolved ✅

Timeline

  • 2026-01-26 10:00: User reported the Audiobookshelf (ABS) library appeared empty/deleted.
  • 2026-01-26 10:15: Initial investigation confirmed the /audiobooks directory was intact on the host (holodeck-subspace).
  • 2026-01-26 10:30: Analysis of Docker logs revealed thousands of TypeError and AudioFileScanner errors occurring during recursive scans of the downloads subdirectory.
  • 2026-01-26 10:45: Identified that the downloads/incomplete folder contained over 13,000 files, causing the scanner to stall or crash.
  • 2026-01-26 11:00: Implemented isolation strategy:
    • Renamed downloads to .downloads_hidden.
    • Created a dedicated /audiobooks/organized directory.
    • Moved all valid book folders into the organized directory.
  • 2026-01-26 11:15: Updated ABS API to point to the new sub-directory and triggered a full rescan.
  • 2026-01-26 11:30: Confirmed library recovery (81+ items indexed).

Root Cause

The Audiobookshelf library root was set to /audiobooks, which included the downloads directory. Because BitTorrent clients (managed by Readarr) were saving incomplete files and thousands of small metadata fragments in downloads/incomplete, the ABS recursive scanner attempted to parse every fragment as a potential audiobook. This exhausted memory/CPU resources and triggered software exceptions, preventing the scanner from ever reaching the actual organized books.

Resolution

  1. Isolation: The library root was changed from /audiobooks to /audiobooks/organized.
  2. Hiding Noise: The downloads folder was renamed to .downloads_hidden on the host filesystem. Even if ABS were pointed at the parent, it would ignore the hidden directory.
  3. Permissions: Verified that all moved files maintained the 3000:3000 ownership standard.

Prevention & Follow-up

  • Architectural Standard: All media services must point to an "organized" or "media" subdirectory, NEVER the root download directory.
  • Automation Update: Readarr's "Root Folder" should be updated to /audiobooks/organized to ensure newly downloaded books are placed in the correct location for ABS to scan.
  • Monitoring: Monitor the scan completion to ensure all ~100+ books are correctly identified with metadata.