The black screen after a staged upgrade
You run the upgrade command, wait for the download to finish, and reboot. The screen stays black. Or you land in a dracut emergency shell. Or the system boots but half your desktop environment is missing. A failed dnf system-upgrade leaves the system in a half-applied state. The transaction rolled back partially, or the initramfs failed to mount the root filesystem because package versions no longer match the boot parameters.
This happens more often than you think. The upgrade process is not a live patch. It stages a complete transaction and applies it on the next boot before the main system starts. If anything breaks during that early phase, you need to know where to look and how to reset the transaction cleanly.
What the upgrade process actually does
Think of dnf system-upgrade like a contractor who drops off all the materials, locks the doors, and does the work while you are away. The command downloads every package required for the new release, resolves dependencies, and writes a transaction script to /var/lib/dnf/system-upgrade/. When you run the reboot command, a special initramfs hook intercepts the boot process. It mounts the root filesystem read-only, applies the transaction, updates the initramfs, and then hands control to the normal boot sequence.
If the download phase fails, the transaction file is incomplete. If the boot-phase application fails, the system cannot finish mounting or starts with mismatched libraries. The package manager protects the system by refusing to continue if it detects a broken state. You will see a dependency conflict or a missing file error. The system stops to prevent a corrupted root filesystem.
Run journalctl -b -1 to read the previous boot log. The -b -1 flag jumps to the last boot cycle, which is where the upgrade attempt happened. Most failures leave a clear trace there.
Recovering from a failed transaction
Start by checking whether the upgrade transaction is still marked as pending. A stuck transaction blocks normal dnf operations and can cause confusing dependency errors.
Here is how to check the current upgrade state and clear a stuck transaction.
sudo dnf system-upgrade status
# Shows whether a transaction is pending, running, or clean.
# If it says "pending", the system is waiting for the reboot phase.
# If it says "clean", the transaction was already reset or completed.
sudo dnf system-upgrade cancel
# Removes the pending transaction file from /var/lib/dnf/system-upgrade/.
# This frees dnf to operate normally again and prevents ghost dependencies.
Once the transaction is cleared, verify your available disk space. The original guidance mentions 200GB for build environments. A standard system upgrade only needs 10 to 15GB of free space on the root partition. The package manager needs room to cache downloaded RPMs, extract them, and write the new initramfs before cleaning up. If your partition is smaller than that, the download phase will abort with a disk full error.
Here is how to check free space and clean the cache safely.
df -h /
# Shows available space on the root filesystem.
# Look at the "Avail" column. Anything under 10GB is risky for a full release upgrade.
sudo dnf clean all
# Purges cached metadata and leftover RPM headers.
# Frees space and forces dnf to fetch fresh repo information on the next run.
sudo dnf upgrade --refresh
# Applies all pending updates for your current release.
# Always bring the base system to the latest point release before crossing major versions.
With a clean state and enough space, re-run the upgrade. Use the --releasever flag to target the exact Fedora version you want. Fedora follows a six-month release cadence. The N-2 release goes end-of-life when N+1 ships. Plan your upgrades on that cycle to avoid running unsupported packages.
Here is the correct sequence to download and stage the upgrade.
sudo dnf system-upgrade download --releasever=43
# Fetches all packages for Fedora 43 and writes the transaction script.
# Do not interrupt this step. A partial download corrupts the transaction.
sudo dnf system-upgrade reboot
# Triggers the special initramfs hook that applies the staged transaction.
# The system will reboot automatically and begin the upgrade process.
If the download fails with a repository error, check your third-party sources. RPM Fusion, Flatpak runtimes, and custom .repo files often break during major version jumps. Disable them temporarily, run the download, then re-enable them after the new release boots.
Clear the pending transaction before you guess. A stuck upgrade state blocks every other package operation.
Verify the system state
After the reboot completes, confirm that the new release is actually active. Do not assume the desktop environment loading means the upgrade succeeded. The system could be running the old kernel with partially updated userspace packages.
Here is how to verify the release version and package consistency.
cat /etc/fedora-release
# Prints the active release string.
# Should match the target version you specified in the download command.
sudo dnf check
# Scans the installed RPM database for broken dependencies.
# Returns "No problems found" if the transaction applied cleanly.
If dnf check reports conflicts, do not force-remove packages. The conflict usually points to a leftover third-party RPM or a mismatched kernel module. Identify the offending package, remove it with sudo dnf remove <package>, and run sudo dnf distro-sync to align the remaining packages with the official repositories.
Check the boot log for SELinux relabeling messages. The first boot after a major upgrade often triggers a full filesystem relabel. This process can take several minutes on a large drive. The system will appear frozen at the login screen. Wait it out. Interrupting a relabel corrupts file contexts and forces a manual restorecon run.
Run journalctl -xe to read the current boot state. The x flag adds explanatory context to error lines. The e flag jumps to the end of the log. Most sysadmins type journalctl -xeu <unit> muscle-memory style when tracking a specific service failure.
Trust the package manager. Manual file edits drift, snapshots stay.
Common failure modes and how to read them
Upgrades fail for predictable reasons. Knowing the exact error string saves hours of trial and error.
The dnf system-upgrade download command 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. Fedora does not ship multiple major Python versions in the base repos. Remove the conflicting third-party package or switch to the official repository version before retrying.
If you see [FAILED] Failed to start NetworkManager.service during the early boot phase, your network configuration probably references a missing interface name or a removed driver. The upgrade replaced the kernel or firmware package, and the old udev rules no longer match the hardware. Check /etc/NetworkManager/conf.d/ for hardcoded interface names and switch to MAC address or connection UUID matching.
Config files in /etc/ are user-modified. Files in /usr/lib/ ship with the package. Edit /etc/. Never edit /usr/lib/. The package manager will overwrite /usr/lib/ on the next update and silently revert your changes.
A dracut emergency shell usually means the initramfs cannot find the root filesystem. This happens when the kernel upgrade changes the storage driver or when LUKS encryption keys are not passed correctly. The shell will print dracut: Refusing to start rootless shell or dracut: Cannot find device with uuid=.... Boot the previous kernel from the GRUB advanced menu, run sudo dracut --force to rebuild the initramfs with the current kernel, and reboot.
Firewall rules and SELinux policies do not carry over automatically if you manually edited the runtime configuration. Run firewall-cmd --reload after every rule change. Otherwise the runtime config and the persistent config diverge, and services fail to bind to ports after a reboot.
SELinux denials show up in journalctl -t setroubleshoot with a one-line summary. Read those before disabling SELinux. Most upgrade-related denials are caused by stale file contexts on custom scripts or third-party binaries. Run sudo restorecon -Rv /path/to/directory to fix them.
Reboot before you debug. Half the time the symptom is gone.
Choose the right upgrade path
Different tools serve different workflows. Pick the one that matches your system state and risk tolerance.
Use dnf system-upgrade when you want a clean, in-place transition between major Fedora releases. Use dnf upgrade --refresh when you only need to apply security patches and bug fixes within the current release. Use a fresh installation when your system has accumulated years of manual tweaks, broken third-party repos, or custom kernel patches. Use Silverblue when you want a known-good base image you can always roll back to. Use Workstation when you need to install kernel modules or low-level driver patches. Use Server when you are running services and not a desktop. Stay on the upstream Workstation if you only deviate from the defaults occasionally.
Snapshot the system before the upgrade. Future-you will thank you.