You interrupted the upgrade and now nothing works
You ran sudo dnf upgrade and the power went out. Or the network dropped halfway through. Or you killed the process because it was taking too long. Now dnf screams about broken dependencies, or a package refuses to install because systemd is in a weird state. The terminal is red. You can't install anything new, and you're worried the system is toast. It isn't. The package database is just confused. You can fix this without reinstalling the OS.
The package database is a catalog, not the shelf
Think of the RPM database as a library catalog. The packages are the books on the shelves. When dnf installs a package, it writes the book's details to the catalog and puts the book on the shelf. If the process gets interrupted, the catalog might say a book is there when it isn't, or the book is on the shelf but the catalog doesn't know about it. dnf trusts the catalog. If the catalog is wrong, dnf refuses to do anything because it thinks the library is in chaos. You need to reconcile the catalog with the shelves.
Most breakage comes from metadata drift, not missing files. The database thinks a package is version 1.0, but the files on disk are version 1.1. Or the dependency solver sees a conflict because a third-party repo changed its packages while you were offline. The fix is almost always a sequence of checks, syncs, and targeted reinstalls. Start with the least invasive step and work your way down.
Step 1: Diagnose and clear stale metadata
Start by asking dnf what it thinks is wrong. Then clear the cache. Stale metadata causes phantom errors where dnf thinks a package is missing or outdated when it isn't. Fedora mirrors update frequently. Your local cache might be holding onto old headers that conflict with the current repository state.
Here's how to check for dependency errors and refresh the metadata.
sudo dnf check
# WHY: Scans the local database for dependency conflicts and reports them.
# Run this first to see if dnf can diagnose the issue automatically.
# A clean run with no output means the database is internally consistent.
sudo dnf clean all
# WHY: Removes cached metadata and headers from /var/cache/dnf.
# Stale cache files can make dnf think packages are missing or outdated.
# This forces dnf to fetch fresh data on the next command.
sudo dnf makecache
# WHY: Downloads fresh metadata from all enabled repositories.
# Ensures dnf has the current view of available packages before attempting repairs.
# Run this after cleaning to verify your repos are reachable.
Run dnf check again after the cache refresh. If it returns nothing, the cache was the culprit. Your system is fine.
Step 2: Reconcile versions with distro-sync
If dnf check reports errors, the installed packages might be out of sync with the repositories. Maybe you downgraded manually, or a repo changed, or an interrupted upgrade left packages at mismatched versions. distro-sync is the heavy hammer. It forces the installed package set to match the repository versions exactly. This can upgrade, downgrade, or remove packages.
Here's how to sync your system with the repository state.
sudo dnf distro-sync
# WHY: Upgrades, downgrades, or removes packages to match the repository versions.
# This is safer than a full reinstall because it respects the repository state.
# Use this when packages are stuck at wrong versions or have dependency drift.
# Read the transaction summary carefully before confirming.
distro-sync can downgrade packages. If you manually installed a newer kernel or a beta package, distro-sync will pull it back to the stable version. Review the list of changes. Confirm only if the changes look intentional.
Check for .rpmnew files after a sync. When distro-sync updates a configuration file that you have modified, it saves the new version as .rpmnew instead of overwriting your changes.
sudo find /etc -name "*.rpmnew"
# WHY: Finds configuration files that were updated but not applied.
# These files contain the new defaults from the package.
# Compare them with your current config and merge changes manually.
Read the transaction summary carefully. distro-sync can downgrade packages. Confirm only if the changes look intentional.
Step 3: Reinstall corrupted packages
Sometimes one package is corrupted. Files are missing, or permissions are wrong, or the binary is truncated. reinstall fetches the package again and replaces the files. This is faster and safer than removing and reinstalling because it preserves the package state and avoids dependency churn.
Here's how to replace files for a specific package.
sudo dnf reinstall <package-name>
# WHY: Downloads the package and replaces all files without removing the package.
# Fixes missing binaries, corrupted configs, or permission errors.
# Example: sudo dnf reinstall bash
# Reinstalling preserves your configuration files in /etc.
Reinstalling preserves your configuration files in /etc. Your settings stay intact. Only the package files in /usr and /var get replaced.
Reinstalling preserves your configuration files in /etc. Your settings stay intact.
Step 4: Undo a bad transaction
If a recent transaction broke things, undo it. dnf keeps a journal of every operation. You can revert the system to the state before the breakage. This works for installs, upgrades, and removals. It doesn't work for manual file edits or rpm commands run outside dnf.
Here's how to find and undo a transaction.
sudo dnf history list
# WHY: Shows a numbered list of all past transactions.
# Look for the transaction ID that caused the breakage.
# The ID is the number in the first column.
sudo dnf history info <transaction-id>
# WHY: Shows details of a specific transaction.
# Confirms which packages were added, removed, or updated.
# Verify this is the transaction you want to undo.
sudo dnf history undo <transaction-id>
# WHY: Reverses the changes from a specific transaction.
# Restores packages to their previous state.
# Only works for transactions recorded in the dnf history database.
Check the history list before undoing. Undoing a transaction that removed a package will reinstall it.
Check the history list before undoing. Undoing a transaction that removed a package will reinstall it.
Step 5: Repair the RPM database
If dnf and rpm both fail, the database files might be corrupted. This is rare but happens after crashes or disk errors. The database lives in /var/lib/rpm. If the indexes are broken, dnf can't query packages. rpm --rebuilddb rebuilds the indexes from the package metadata.
Here's how to rebuild the database.
sudo rpm --rebuilddb
# WHY: Rebuilds the RPM database indexes from the package metadata.
# Fixes corruption in the Berkeley DB files under /var/lib/rpm.
# Run this only when dnf and rpm commands hang or crash.
# This command can take a few minutes on a large system.
If rpm --rebuilddb fails or hangs, the database might be locked by a stuck process. Move the lock files and try again.
sudo mv /var/lib/rpm/__db* /tmp/
# WHY: Removes stale lock files that prevent database access.
# These files are recreated automatically by rpm.
# Only do this if rpm --rebuilddb hangs indefinitely.
sudo rpm --rebuilddb
# WHY: Rebuilds the database after clearing locks.
# Should succeed if the lock was the only issue.
If rpm --rebuilddb fails, move the lock files. The database is likely locked by a stuck process.
Step 6: Handle orphans and extras
Packages not in any enabled repository cause noise. They can't be updated and may cause dependency issues if other packages expect them to be a certain version. dnf list extras shows these packages. Review the list. Remove packages you no longer need.
Here's how to find and clean up orphans.
sudo dnf list extras
# WHY: Lists installed packages that are not available in any enabled repository.
# These packages cannot be updated and may cause dependency issues.
# Review the list and remove packages you no longer need.
# Common culprits include old kernels, removed third-party tools, or manual rpms.
sudo dnf remove <package-name>
# WHY: Removes an orphaned package and its dependencies.
# Use this to clean up packages that are no longer in the repos.
# Only remove packages you are sure you don't need.
Remove extras that are no longer needed. They accumulate over time and clutter the system.
Remove extras that are no longer needed. They accumulate over time and clutter the system.
Verify the repair
Confirm the system is clean. dnf check verifies dependency consistency. rpm -Va verifies file integrity. Run both.
Here's how to verify the package set is healthy.
sudo dnf check
# WHY: Verifies that no dependency conflicts remain in the database.
# A clean run with no output means the package set is consistent.
# If this reports errors, the repair is incomplete.
sudo rpm -Va 2>/dev/null | grep -v '^......G'
# WHY: Checks all installed files against the RPM database.
# Filters out GPG signature differences which are normal.
# Any remaining output indicates modified or missing files.
# The output format shows file attributes that differ.
The rpm -Va output shows a string of characters for each modified file. 5 means size changed. S means size changed. M means mode changed. D means device changed. L means symlink changed. U means user changed. G means group changed. T means mtime changed. P means capabilities changed. If you see modified files in /etc, check if you changed them manually. Manual edits are expected.
If rpm -Va shows modified files in /etc, check if you changed them manually. Manual edits are expected.
Common pitfalls and error patterns
You might see Error: Transaction test error: package kernel-5.14.0 conflicts with kernel-5.15.0. This usually means you have kernel packages from different sources. Remove the conflicting kernel or disable the third-party repo. Don't force the install. Forcing breaks the system.
You might see Error: Package: ... Requires: .... This is a missing dependency. Run dnf distro-sync to fix version drift. If the dependency is from a third-party repo, enable that repo or remove the package.
Don't use --skip-broken. This flag tells dnf to ignore broken dependencies and continue. This leaves the system in a half-state. Packages will be missing files or have unresolved dependencies. The system will degrade over time. Fix the root cause instead.
Third-party repos like RPM Fusion or Flatpak can cause conflicts. If you added a repo and then broke the system, disable the repo and run distro-sync. Fedora's release cadence is 6 months. The N-2 release goes EOL when N+1 ships. Plan upgrades on that cycle. Don't mix repos from different Fedora versions.
SELinux denials can look like broken packages. If dnf works but apps fail to start, check SELinux. restorecon fixes context issues.
sudo restorecon -Rv /path/to/directory
# WHY: Restores SELinux security contexts to default values.
# Fixes access denied errors caused by wrong labels.
# Run this after moving files or reinstalling packages.
Trust the package manager. Manual file edits drift, snapshots stay.
When to use which repair method
Use dnf distro-sync when packages are out of sync with the repository versions. Use dnf reinstall when a specific package has corrupted files or missing binaries. Use dnf history undo when a recent transaction introduced the breakage. Use rpm --rebuilddb when dnf and rpm commands hang or crash due to database corruption. Use dnf clean all when metadata errors persist after a network interruption. Stay on the default repositories if you only need standard packages.