# 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
```

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:

```yaml
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:

```bash
# 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:

```bash
# 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:

```yaml
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:

```bash
# 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
```

```bash
# 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:

```bash
docker compose restart calibre-web
```

### Method 4: Fix Database Corruption

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

```bash
# 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`:

```bash
# 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](/apps/calibre-web)
- [Best Self-Hosted Ebook Managers](/best/ebooks-reading)
- [Kavita vs Calibre-Web](/compare/kavita-vs-calibre-web)
- [Docker Compose Basics](/foundations/docker-compose-basics)
- [Docker Volumes Guide](/foundations/docker-volumes)