You run dnf upgrade and the terminal freezes
You run sudo dnf upgrade and the terminal hangs. You wait five minutes. Nothing happens. You press Ctrl+C and try again. This time you get a wall of text ending in Error: rpmdb: BDB0113 Thread/process ... died unexpectedly... or database is locked. You try rpm -q firefox and get the same lock error. The package manager is dead in the water.
This happens when the RPM database gets out of sync with the actual files on disk. It usually follows a power loss during an update, a kernel panic, or a manual file move that bypassed the package manager. The system is not broken. The files are still there. The index that tracks them is damaged. You can rebuild the index from the files.
The RPM database is a catalog, not the library
The RPM database lives in /var/lib/rpm. It is an index of every package installed on your system. It records package names, versions, dependencies, and the list of files each package owns. Think of it as a library catalog. The actual packages are the books sitting on the shelves in /usr and /etc. The catalog tells the librarian what is available and where it is.
dnf is the librarian. It takes your request, checks the catalog, resolves dependencies, and tells rpm to install or remove packages. rpm is the system that actually moves files and updates the catalog. When the catalog is corrupted, dnf cannot check books in or out. It sees the error and stops.
The database is a derivative artifact. It is built from the package headers stored on disk. The files in /usr and /etc are the source of truth. If the catalog is torn, you can reconstruct it from the books. Modern Fedora uses SQLite for the RPM database backend. Older releases used Berkeley DB. The repair commands are the same regardless of the backend. The rpm tool abstracts the storage details.
dnf has its own cache in /var/cache/dnf. This cache stores metadata from remote repositories. It is separate from the RPM database. Users often confuse the two. Running dnf clean all clears the remote metadata cache. It does not fix a corrupted local RPM database. You need rpm --rebuilddb to repair the local index.
Run rpm --rebuilddb before you panic. The database is recoverable in almost every case.
Rebuild the database
Stop any running package management processes first. A stuck dnf process holds a lock file that will block your repair attempts. Modern Fedora uses systemd timers for background updates. Stop those to ensure a clean state.
Here is how to stop background package managers and prevent interference.
sudo systemctl stop dnf-makecache.timer # WHY: Disables the timer that triggers background cache updates
sudo systemctl stop dnf.service # WHY: Stops any active transaction unit that might hold locks
sudo systemctl stop dnf-makecache.service # WHY: Halts a running cache update if it is in progress
Attempt the non-destructive rebuild. This command scans the installed package headers and reconstructs the internal database tables. It preserves the existing data while fixing index corruption. This resolves the issue in the majority of cases.
Here is the command to rebuild the RPM database index.
sudo rpm --rebuilddb # WHY: Reconstructs database indexes from installed package headers
If the command completes without error, the database is fixed. If you see error: cannot open Packages index using db5 - Invalid argument or error: db5 error(-30974) from dbenv->open: BDB0060 DB_RUNRECOVERY: Fatal error, run database recovery, the database structure is too damaged for a simple rebuild. You need to clear the lock files and force a regeneration.
Here is how to remove stale lock files and force a database regeneration.
sudo rm -f /var/lib/rpm/__db.* # WHY: Removes Berkeley DB lock and journal files that cause stale locks
sudo rm -f /var/lib/rpm/.rpm.lock # WHY: Deletes the rpm lock file if it persists after service stop
sudo rpm --rebuilddb # WHY: Rebuilds the database after clearing lock artifacts
If rpm --rebuilddb still fails, check whether the Packages file itself is corrupted. The Packages file contains the raw package records. If it is zero bytes or contains garbage, rpm cannot rebuild the indexes. In that case, the database is unrecoverable without a backup. Do not delete the Packages file. Deleting it breaks the system irrecoverably. dnf cannot recreate the RPM database from scratch. The package manager relies on the RPM database to function. If the Packages file is gone, you must restore it from a backup or reinstall the system.
Trust the package manager. Manual file edits drift, snapshots stay.
Verify the repair
Confirm the database is functional by querying a core package. If rpm can return version information, the index is working. Then run dnf check to verify dependency resolution.
Here is how to verify the database integrity and package consistency.
rpm -q fedora-release # WHY: Confirms rpm can query the database for a core package
rpm -q dnf # WHY: Verifies the package manager itself is registered in the database
dnf check # WHY: Validates package dependencies and detects conflicts
If dnf check returns no output, the system is healthy. If it lists broken dependencies, the database is fixed but some packages are in an inconsistent state. You can resolve dependency issues with sudo dnf distro-sync. This command aligns installed packages with the repository versions and fixes dependency mismatches.
Run journalctl -xe first. Read the actual error before guessing.
Common pitfalls and error patterns
SELinux context errors
If you restored files from a backup or manually copied files into /var/lib/rpm, the SELinux contexts might be wrong. rpm and dnf will fail with permission denied errors even if the Linux permissions are correct. SELinux enforces mandatory access control based on file labels.
Here is how to restore correct SELinux contexts on the RPM database directory.
sudo restorecon -Rv /var/lib/rpm # WHY: Resets SELinux contexts to the policy defaults recursively
The -v flag prints each file as it is relabeled. If you see changes, the contexts were incorrect. Run rpm --rebuilddb again after restoring contexts.
Filesystem corruption
If rpm --rebuilddb fails with I/O errors or Input/output error, the underlying filesystem might be damaged. The database corruption is a symptom of a deeper problem. Check the kernel log for disk errors.
Here is how to check for filesystem errors in the kernel log.
journalctl -k | grep -i error # WHY: Filters kernel messages for hardware or filesystem errors
dmesg | grep -i ext4 # WHY: Checks for filesystem-specific errors if using ext4
If you see errors like EXT4-fs error or I/O error, run a filesystem check. Boot from a live USB or recovery mode and run fsck on the root partition. Do not run fsck on a mounted filesystem.
Stale lock files
Sometimes the database is fine, but a lock file remains from a crashed process. dnf refuses to run and prints Another app is currently holding the dnf lock. The lock file is in /var/run/yum.pid or managed by systemd.
Here is how to remove stale lock files safely.
sudo rm -f /var/run/yum.pid # WHY: Removes the legacy lock file if it persists
sudo systemctl reset-failed dnf.service # WHY: Clears the failed state from systemd
After removing the lock, try dnf upgrade again. If the error persists, check for a zombie process with ps aux | grep dnf. Kill the process if it is stuck.
Confusing dnf cache with rpm database
Users often run dnf clean all when they encounter RPM errors. This clears the repository metadata cache. It does not repair the local RPM database. The RPM database tracks installed packages. The dnf cache tracks available packages from repositories. They are separate systems.
Use dnf clean all when repository metadata is out of date. Use rpm --rebuilddb when the local package index is corrupted.
Snapshot the system before the upgrade. Future-you will thank you.
Decision matrix
Use rpm --rebuilddb when the database is locked or indexes are out of sync. Use restorecon when you see permission denied errors after restoring files from backup. Use fsck when rpm --rebuilddb fails with I/O errors or kernel log shows filesystem errors. Restore from backup when the Packages file is corrupted and rpm --rebuilddb cannot recover. Reinstall the system when the database is unrecoverable and no backup exists.