Fixing a Corrupted Plex Database (Unraid, Docker, or Bare Metal)

Fix a corrupted Plex database on Unraid, Docker, or bare metal with PlexDBRepair. Step-by-step guide to stop Plex, repair, and restart.

Fixing a Corrupted Plex Database (Unraid, Docker, or Bare Metal)
Broken Plex database icon

If you’ve run Plex long enough, you’ve probably hit the dreaded database corruption issue. Suddenly Plex won’t load your library, or you get weird behavior when browsing media. The good news is Plex ships with a built-in repair utility, and you can use it whether you’re running Plex in Unraid, in a Docker container, or directly on Windows/Linux/macOS.

This post will walk you through how to safely stop Plex, run the repair, and start it back up.

Why Plex Database Corruption Happens

Plex uses an SQLite database (com.plexapp.plugins.library.db) to track all your media, metadata, and watched states. Like any database, if Plex is interrupted while writing to it (power outage, forced restart, filesystem hiccup), the file can get corrupted. Symptoms include:

  • Plex not starting at all
  • Libraries missing or refusing to scan
  • Searches returning nothing

The Official Repair Tool: 

PlexDBRepair

Plex bundles a repair script called PlexDBRepair (or DBRepair.sh depending on your distribution). It can often salvage a corrupted database without you needing to restore from backup.

Step 1: Stop Plex Safely

If you’re running Plex in Docker (Unraid, binhex-plex, linuxserver/plex):

You don’t need to stop the container, just stop the Plex Media Server daemon inside it.
For example with binhex-plex:

docker exec binhex-plex supervisorctl stop plexmediaserver

Or if that doesn’t work:

docker exec binhex-plex pkill -f "Plex Media Server"

If that doesn't work and you are using Unraid you can try and connect to the container's console and manage it from there.

  1. Open a shell into your container From Unraid, go to the Docker tab in the web UI, click the dropdown arrow next to your Plex container, and choose Console.Or from a terminal, run:
docker exec -it binhex-plex bash

(replace binhex-plex with your container name — you can see it under docker ps).Now you’re inside the container as if it were its own mini-Linux system.

  1. Stop the Plex daemon Inside the container shell, try the official way first:
supervisorctl stop plexmediaserver

If that returns “no such process” or Plex keeps running, use a process kill:

pkill -f "Plex Media Server"

You can verify it stopped with:

ps aux | grep -i plex

If you’re running Plex on bare metal (Windows/macOS/Linux):

  • On Windows: stop the Plex service from Services.msc or exit it from the tray icon.
  • On Linux:
sudo systemctl stop plexmediaserver
  • On macOS: quit Plex from the menu bar.

Step 2: Run the Repair Script

The repair script location depends on how Plex is installed:

  • Unraid/Docker (binhex-plex):
docker exec binhex-plex /usr/local/bin/DBRepair.sh auto
  • Linux (official package):
/usr/lib/plexmediaserver/PlexDBRepair
  • macOS:Located under the Plex app bundle, usually:
/Applications/Plex Media Server.app/Contents/MacOS/PlexDBRepair
  • Windows:Run from the Plex installation folder:
"C:\Program Files (x86)\Plex\Plex Media Server\PlexDBRepair.exe"

The auto option attempts to run a full check/repair sequence automatically.

Step 3: Start Plex Again

  • Docker/Unraid:
docker restart binhex-plex
  • Linux:
sudo systemctl start plexmediaserver
  • macOS / Windows: Just launch Plex again.

What I do - Automating Nightly Maintenance on Unraid

If you’d like to automatically run a repair check once a night:

  1. Install the User Scripts plugin in Unraid.
  2. Create a script like this:
#!/bin/bash
echo "=== Plex Maintenance Started: $(date) ==="

# Stop Plex daemon
docker exec binhex-plex pkill -f "Plex Media Server"
sleep 10

# Run DB repair
docker exec binhex-plex /usr/local/bin/DBRepair.sh auto

# Restart Plex container
docker restart binhex-plex

echo "=== Plex Maintenance Finished: $(date) ==="
  1. Schedule it for 3 AM daily or some time outside of your backup window

Stuff to think about

  • Backup first: Your Plex database lives in Plex Media Server/Plug-in Support/Databases/. Copy it before running repair.
  • Use Uptime Kuma or similar monitoring: If you monitor Plex uptime, you can automatically put it in maintenance mode before repair so alerts don’t fire.
  • If repair fails: Restore from a database backup (com.plexapp.plugins.library.db-<timestamp>.bak) found in the same folder.

Conclusion

Whether you’re running Plex on bare metal, inside Docker, or on Unraid, the database repair process is very similar. The key is:

  1. Stop Plex
  2. Run PlexDBRepair
  3. Restart Plex

With a little automation, you can even run it nightly to catch corruption early.

Got any other suggestions? Leave it in the comments.