Calibre-Web: Books Not Loading — Fix

The Problem

Calibre-Web starts but shows an empty library, displays “DB Location is not Valid” on the setup page, or throws errors like:

calibre-web  | [ERROR] [cps.web] Cannot access metadata.db
calibre-web  | [ERROR] DatabaseException: database is not configured

You can access the web UI but can’t see any books, or the initial setup page keeps rejecting the database path.

The Cause

Calibre-Web requires a valid Calibre metadata.db file to function. Unlike other apps that create their own database on first run, Calibre-Web reads an existing Calibre library. The most common issues are:

1. Wrong database path — the container path doesn’t point to where metadata.db actually lives
2. File permissions — the container user can’t read metadata.db or the library directory
3. No Calibre library exists — you mounted an empty directory without first creating a library in Calibre desktop
4. Volume mount mismatch — the host path exists but the container mount doesn’t match what you entered in the setup wizard

The Fix

Method 1: Verify the Database Path (Most Common)

On the Calibre-Web setup page (or in the admin settings), the “Location of Calibre Database” must point to the container path where metadata.db lives — not the host path.

If your Docker Compose has:

volumes:
  - /home/user/calibre-library:/books

Then the database path in Calibre-Web must be /books — not /home/user/calibre-library.

Verify metadata.db exists at the mounted location:

# Check from outside the container
ls -la /home/user/calibre-library/metadata.db

# Check from inside the container
docker exec calibre-web ls -la /books/metadata.db

If metadata.db doesn’t exist, you need to create a Calibre library first (see Method 3).

Method 2: Fix File Permissions

The LinuxServer.io image runs as the user specified by PUID and PGID. The library directory and metadata.db must be readable by that user:

# Check current ownership
ls -la /home/user/calibre-library/metadata.db

# Fix permissions (use the same PUID/PGID from your docker-compose.yml)
sudo chown -R 1000:1000 /home/user/calibre-library/
sudo chmod -R 755 /home/user/calibre-library/

If you’re using the official lscr.io/linuxserver/calibre-web image, ensure your Compose file includes:

environment:
  - PUID=1000
  - PGID=1000

These must match the owner of the library directory on the host.

Method 3: Create a Calibre Library (If None Exists)

Calibre-Web cannot create a library from scratch. You need a metadata.db file created by Calibre desktop or the Calibre CLI:

# Option A: Create an empty library with calibredb
# Install Calibre CLI tools first
sudo apt install calibre

# Initialize an empty library
calibredb --library-path /home/user/calibre-library list

# This creates metadata.db in the specified directory

# Option B: Download Calibre desktop, create a library, add at least one book, then copy the directory to your server

After creating the library, restart Calibre-Web:

docker compose restart calibre-web

Method 4: Fix Database Corruption

If metadata.db exists but Calibre-Web still can’t read it:

# Check database integrity
sqlite3 /home/user/calibre-library/metadata.db "PRAGMA integrity_check;"
# Should output: ok

# If corrupted, restore from backup
cp /home/user/calibre-library/metadata_db_prefs_backup.json /tmp/
# Then recreate the library from Calibre desktop

Method 5: Fix Read-Only Filesystem Errors

If the container logs show database is locked or attempt to write a readonly database:

# Ensure the volume is not mounted read-only
# WRONG:
volumes:
  - /home/user/calibre-library:/books:ro

# CORRECT (Calibre-Web needs write access):
volumes:
  - /home/user/calibre-library:/books

Calibre-Web writes to metadata.db when you edit metadata, add books, or update covers. It needs read-write access.

Prevention

• Always verify metadata.db exists before starting Calibre-Web for the first time
• Use consistent PUID/PGID values that match the library directory owner
• Back up metadata.db regularly — it’s the critical file for your entire library
• When migrating, copy the entire Calibre library directory (not just metadata.db)
• Test the database path from inside the container, not from the host

Related

• How to Self-Host Calibre-Web
• Best Self-Hosted Ebook Managers
• Kavita vs Calibre-Web
• Docker Compose Basics
• Docker Volumes Guide