DEV Community

selfhosting.sh
selfhosting.sh

Posted on • Originally published at selfhosting.sh

Calibre Web Not Loading

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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/
Enter fullscreen mode Exit fullscreen mode

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

environment:
  - PUID=1000
  - PGID=1000
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode 
# Option B: Download Calibre desktop, create a library, add at least one book, then copy the directory to your server
Enter fullscreen mode Exit fullscreen mode

After creating the library, restart Calibre-Web:

docker compose restart calibre-web
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

Top comments (0)