Story / scenario opener
You run a routine dnf upgrade and the transaction aborts halfway through. The terminal spits out a wall of red text about missing libraries, conflicting packages, or unsatisfied dependencies. Your system is stuck in a half-broken state, and you need to get back to a working desktop before your next meeting.
What's actually happening
Package managers like DNF and RPM work like a strict librarian. Every package declares exactly which other packages it needs to function. When you ask DNF to install or upgrade something, it builds a dependency graph. It checks every declared requirement against your local cache and the configured repositories. If a single requirement is missing, version-mismatched, or blocked by a conflicting package, the solver stops. It refuses to proceed because installing a broken dependency chain would leave your system in an inconsistent state.
Think of it like assembling furniture. The manual says you need a specific screw, a matching bracket, and a pre-drilled hole. If the bracket is the wrong size, you do not force the screw in. You find the correct bracket first. DNF follows the same rule. It protects your system by refusing to install mismatched components.
Under the hood, RPM tracks four dependency types: requires, provides, conflicts, and obsoletes. A requires tag declares what a package needs. A provides tag declares what a package offers to satisfy other packages. A conflicts tag prevents two incompatible packages from coexisting. An obsoletes tag tells the solver to automatically remove an older package when a newer one is installed. DNF's solver evaluates all four tags simultaneously. When the graph contains a cycle or an unresolvable node, the solver throws a dependency error and halts.
The fix
Start by clearing the local metadata cache. Stale repository data is the most common cause of false dependency failures. DNF caches package lists and checksums to speed up operations. When a repository updates its metadata but your local cache still holds the old version, the solver sees a ghost dependency that no longer exists.
Here is how to flush the cache and force a fresh metadata pull.
sudo dnf clean all # Removes cached repository metadata and package files
sudo dnf makecache # Downloads fresh metadata from all enabled repositories
sudo dnf upgrade --refresh # Forces re-download of metadata before solving the transaction
Run the upgrade command again. If the solver still fails, you are likely dealing with a repository conflict or a third-party repository that is out of sync with Fedora's main stream. Check your enabled repositories and look for disabled or misconfigured sources.
dnf repolist all # Lists every repository and shows whether it is enabled or disabled
If you see a third-party repository with a high priority or an outdated version, disable it temporarily. Fedora's main repositories have a default priority that keeps the core system stable. Third-party sources can introduce version skew that breaks the solver.
sudo dnf config-manager --set-disabled <repo-name> # Disables the problematic repository for the current transaction
sudo dnf upgrade # Retries the transaction using only the stable repositories
When the transaction completes, re-enable the third-party repository if you still need it. Update the repository's configuration to match your current Fedora release version. Repository maintainers often forget to update their metadata URLs after a Fedora release cycle.
If the solver still refuses to proceed, check for orphaned packages. Orphans are packages that were installed manually or pulled in as dependencies but are no longer required by any other package. They can block upgrades because they hold back newer versions of shared libraries.
dnf repoquery --extras # Lists packages not available in any enabled repository
sudo dnf autoremove # Removes orphaned packages and their unused dependencies
Run the upgrade again after cleaning up orphans. If you are still stuck, roll back to a known-good transaction state. DNF keeps a complete history of every package change. You can undo the last failed transaction and start fresh.
dnf history list # Shows a numbered list of past transactions
sudo dnf history undo <transaction-id> # Reverts the system to the state before that transaction
Reboot before you debug. Half the time the symptom is gone.
Verify it worked
Confirm that the package database is consistent and no packages are in a broken state. The rpm database tracks every installed file and its dependencies. A quick consistency check will tell you if the solver left any loose ends.
rpm -Va --nofiles --nodigest # Verifies package metadata without checking file sizes or checksums
dnf check # Scans the installed package set for dependency conflicts
If both commands return nothing, your system is clean. If dnf check prints a conflict, note the package names and run dnf remove on the offending package before retrying the upgrade. Trust the package manager. Manual file edits drift, snapshots stay.
Common pitfalls and what the error looks like
The most frequent error is the transaction test failure. DNF will refuse to proceed and print Error: Transaction test error: package python3-3.12.x conflicts with python3-3.13.y. The conflict is intentional. Read the next paragraph before forcing.
Another common pattern is the missing dependency error. You will see Problem: package foo-1.0 requires libbar.so()(64bit), but none of the providers can be installed. This usually means the repository providing libbar is disabled, or the version in the repository is too old for your current Fedora release.
A third pattern is the modular stream conflict. Fedora uses modules for certain package groups like Python, Node.js, or PostgreSQL. If you see Module stream conflict: module python39 conflicts with installed module python311, you are trying to mix two different module streams. DNF will not allow this because the underlying libraries are not compatible.
Do not use --skip-broken as a first resort. That flag tells DNF to ignore missing dependencies and continue anyway. It leaves your system in a partially upgraded state. Use it only when you are intentionally removing a package that is blocking the transaction, and you understand the consequences.
SELinux denials can also masquerade as dependency errors. If a package fails to start after installation, check the audit logs before assuming the package is broken.
journalctl -t setroubleshoot # Shows SELinux denial summaries with human-readable explanations
Config files in /etc/ are user-modified. Files in /usr/lib/ ship with the package. Edit /etc/. Never edit /usr/lib/. If you manually patched a file in /usr/lib/, RPM will mark the package as modified and refuse to upgrade it until you restore the original. Use dnf reinstall <package> to overwrite manual edits.
When to use this vs alternatives
Use dnf clean all and --refresh when repository metadata is stale or the solver reports missing packages that you know exist. Use dnf check when you suspect a previous transaction was interrupted and left the RPM database in an inconsistent state. Use dnf module reset and dnf module install when you are dealing with modular stream conflicts and need to switch to a different version of a package group. Use rpm -e --nodeps only when you are absolutely certain a package is corrupted and DNF cannot remove it through normal channels. Stay on the default DNF solver for routine upgrades and package installations.