How to Repair a Corrupted Plex Database

Published September 1, 2026 · 10 min read

A corrupted Plex database is one of the most stressful problems a server owner can face. Your watch history, metadata edits, collections, playlists, and user data all live in a single SQLite database file. When that file becomes corrupted, you may see symptoms ranging from minor annoyances (slow browsing, missing thumbnails) to total server failure (Plex refuses to start).

The good news is that SQLite databases are remarkably recoverable. Even heavily corrupted databases can often be repaired, and if repair is not possible, Plex maintains automatic backups you may not know about. This guide walks you through every recovery option, from quick fixes to a full rebuild.

Signs of Database Corruption

Database corruption does not always announce itself with an error message. Often it manifests as subtle degradation that worsens over time. Watch for these symptoms:

• Progressively slower browsing. Library pages that used to load instantly now take several seconds. Search results are delayed. The home screen is sluggish.
• Missing items. Movies, shows, or episodes that exist on disk do not appear in the library, even after rescanning.
• Duplicate entries. The same movie appears multiple times despite only having one file on disk.
• Watch status resets. Items you have watched revert to unwatched, or entire users lose their watch history.
• Plex crashes or hangs. The server process crashes periodically or becomes unresponsive. Check the Plex logs for SQLite error messages like "database disk image is malformed" or "SQLITE_CORRUPT."
• Metadata disappears. Posters, descriptions, or ratings vanish and cannot be re-fetched by refreshing metadata.
• Plex refuses to start. The server process starts but immediately exits. The log file shows database errors on startup.

What Causes Corruption

Understanding the cause helps prevent recurrence:

• Power loss. If the server loses power while the database is being written to, the write-ahead log (WAL) and the main database file can become inconsistent.
• Disk failure. Bad sectors on a hard drive, failing SSD cells, or unreliable USB drives can corrupt any file, including the database.
• Network storage issues. Running the Plex database on a network share (NAS via SMB/NFS) can cause corruption if the network connection is interrupted during a write. This is one reason why running the database on local storage is recommended.
• Forced shutdowns. Killing the Plex process without a graceful shutdown can leave the database in a partially written state.
• Out of disk space. If the disk runs out of space during a database write, the operation fails mid-way and can leave the database inconsistent.
• Software bugs. Rare, but occasionally a Plex update introduces a bug that can damage the database under specific conditions.

Step 1: Back Up the Current Database

Before attempting any repair, make a copy of the current database files. Even a corrupted database is valuable -- you do not want to make things worse by modifying the only copy.

1. Stop Plex Media Server.
2. Navigate to the database directory: Plug-in Support/Databases/ inside your Plex data directory.
3. Copy these three files to a safe location:
   • com.plexapp.plugins.library.db (the main database)
   • com.plexapp.plugins.library.db-wal (write-ahead log)
   • com.plexapp.plugins.library.db-shm (shared memory file)

Keep these copies untouched. If your repair attempts make things worse, you can always start over from this backup.

Step 2: Try the Built-in Database Repair

Plex includes a built-in database repair option. In the Plex Web interface (if the server is running well enough to access it), go to Settings, Troubleshooting, and click "Repair Library." This runs Plex's internal repair routines, which include integrity checks and recovery from the write-ahead log.

If Plex will not start at all, this option is obviously unavailable. Proceed to manual repair.

Step 3: SQLite Manual Repair

SQLite includes built-in integrity checking and recovery commands. You need the sqlite3 command-line tool, which is pre-installed on macOS and most Linux distributions. On Windows, download it from the SQLite website.

Check Integrity

First, check whether the database is actually corrupted:

sqlite3 com.plexapp.plugins.library.db "PRAGMA integrity_check;"

If the database is healthy, this returns "ok." If it is corrupted, it returns a list of errors describing what is wrong. This tells you the severity of the corruption.

Export and Re-Import

The most reliable SQLite repair method is to dump the database to SQL text and reimport it into a new file. This process skips over corrupted pages and recovers everything that is still readable:

# Export the database to a SQL dump
sqlite3 com.plexapp.plugins.library.db ".dump" > plex-dump.sql

# Create a new database from the dump
sqlite3 com.plexapp.plugins.library.db-repaired < plex-dump.sql

If the dump command encounters errors, it may skip some data. Check the output file for ERROR lines. Any skipped data is lost, but the remaining data forms a consistent, uncorrupted database.

Replace the Database

After creating the repaired database:

1. Ensure Plex is stopped.
2. Rename the old database: mv com.plexapp.plugins.library.db com.plexapp.plugins.library.db.corrupt
3. Rename the repaired database: mv com.plexapp.plugins.library.db-repaired com.plexapp.plugins.library.db
4. Delete the old WAL and SHM files (they belong to the old database): rm com.plexapp.plugins.library.db-wal com.plexapp.plugins.library.db-shm
5. Start Plex and verify that your library appears correctly.

Step 4: Plex DB Repair Tool

The community-developed Plex DB Repair tool automates the SQLite repair process and includes Plex-specific fixes that go beyond basic SQLite recovery. It handles WAL file integration, index rebuilding, and other operations specific to the Plex database schema.

The tool is available on GitHub and runs on Linux and macOS. It typically performs these operations in sequence:

1. Stops the Plex service
2. Creates a backup of the current database
3. Integrates the WAL file into the main database
4. Runs integrity checks
5. Performs the dump-and-reimport repair if needed
6. Rebuilds indexes
7. Optimizes the repaired database
8. Restarts Plex

For most users, this tool is the easiest path to repairing a corrupted database. It handles the technical details and provides clear output about what was found and fixed.

Step 5: Restore from Backup

If manual repair fails or the corruption is too severe, your next option is restoring from a backup. Plex automatically backs up the database as part of its scheduled tasks (if you have not disabled that task). These backups are stored in:

Plug-in Support/Databases/

Look for files named like com.plexapp.plugins.library.db-YYYY-MM-DD or compressed backup files. The most recent backup before the corruption occurred is what you want.

To restore:

1. Stop Plex.
2. Move the corrupted database files aside.
3. Copy or decompress the backup file and rename it to com.plexapp.plugins.library.db.
4. Delete any WAL and SHM files.
5. Start Plex.

The restored database will reflect the state of your library at the time the backup was made. Any changes since then (new media added, watch status updates, metadata edits) will be lost. After restoring, run a full library scan to pick up any media files added since the backup.

The Nuclear Option: Full Rebuild

If no backup exists and the database is unrecoverable, the last resort is a complete rebuild. This means starting with a fresh database and rescanning all your media. Here is what you lose and what you keep:

What You Lose

• All watch history and play counts across all users
• All ratings and reviews
• All playlists and collections
• All custom metadata edits (manually changed titles, descriptions, posters you uploaded)
• All user accounts and sharing permissions
• All server settings and preferences

What You Keep

• All media files (movies, shows, music, photos) -- these are on disk, not in the database
• File organization and naming -- Plex will re-match based on your filenames
• Automatic metadata from online agents -- re-fetched during the scan

How to Rebuild

1. Stop Plex.
2. Rename the entire Plex data directory (do not delete it -- you may want to recover metadata artwork later).
3. Start Plex. It will create a fresh data directory with a new empty database.
4. Claim the server with your Plex account.
5. Re-create your libraries pointing to the same media folders.
6. Let Plex scan and match everything. This can take hours for large libraries.
7. Re-invite shared users and reconfigure permissions.
8. Reconfigure server settings (remote access, transcoding, network, etc.).

Preventing Future Corruption

Once you have recovered from database corruption, take steps to prevent it from happening again:

• Use a UPS. An uninterruptible power supply protects against power outages, the most common cause of database corruption. Even a small UPS that provides 10 minutes of runtime gives the server enough time for a clean shutdown.
• Run the database on local storage. Avoid network shares (SMB, NFS) for the database. Local SSD is ideal.
• Keep Plex's scheduled database backup enabled. This is your automatic safety net. Never disable it.
• Monitor disk health. Use SMART monitoring tools to detect failing drives before they corrupt your data.
• Shut down gracefully. Always stop Plex through the proper channels (service stop, menu bar quit, systemctl stop) rather than killing the process or pulling the power.
• Maintain free disk space. Keep at least 10 percent of your system drive free at all times. A full disk during a database write almost guarantees corruption.