About this article: This article is reviewed against the cited sources. This is source research, not lab validation. Check the stated versions and your own requirements before making changes.
When a RHEL 8 to RHEL 9 in-place upgrade will not start, the Leapp pre-upgrade report lists the reason. Run leapp preupgrade, open /var/log/leapp/leapp-report.txt, and clear every problem marked as an inhibitor. Red Hat says "Inhibitor problems prevent you from upgrading until you have resolved them." Fix them one at a time, run the report again, and only start leapp upgrade after a clean report and a backup you have tested.
What the error means
Leapp is Red Hat's in-place upgrade tool. Red Hat describes the pre-upgrade phase this way: Leapp "collects data about the system, assesses upgradability, and generates a pre-upgrade report." The report states potential problems and recommended solutions. The documented risk levels are High ("Very likely to result in a deteriorated system state"), Medium, Low and Info.
Three points from Red Hat's guide matter when you read the report:
- The pre-upgrade assessment "does not modify the system configuration", but it uses space in
/var/lib/leapp: "up to 4 GB". If there is not enough space, the report "might not show complete results of the analysis." - Read the whole report even when it finds no inhibitors: Red Hat says it holds recommended actions to complete before the upgrade.
- The report "cannot simulate the entire in-place upgrade process", so an upgrade can still stop after a clean report, for example on broken package downloads.
Supported paths, per the guide as captured on 13 June 2026 (version numbers come from that capture and may have changed): source RHEL 8.10 only, to RHEL 9.6 (EUS) or RHEL 9.8 for the standard configuration. Direct upgrade from RHEL 7 to RHEL 9 is not possible. The guide asks for leapp 0.21.0 and leapp-repository 0.24.0. Red Hat's note under the table says the paths "are guaranteed only for systems that use Red Hat Subscription Manager (RHSM)", and that for Pay-As-You-Go RHEL systems that use Red Hat Update Infrastructure (RHUI), "only the latest available upgrade path is supported".
Likely causes
| Cause | What you see | How to confirm |
|---|---|---|
| Unanswered question | Report shows "Missing required answers in the answer file" | /var/log/leapp/answerfile has an unanswered confirm = line |
| Packages signed with RSA/SHA-1 | Upgrade inhibited; report names the packages | Red Hat: "If your system contains any packages with RSA/SHA-1 signatures, the upgrade is inhibited" |
| Device driver not in RHEL 9 | Report names a driver Red Hat provides in 8 but not 9 | The driver is listed in the report; Leapp reads /etc/leapp/files/device_driver_deprecation_data.json |
| Wrong repositories on Satellite | Inhibited when only the RHEL 9 repositories are enabled without the target version | Check that the target version, for example 9.8, of each repository is enabled |
| Preparation steps missed | Odd failures: old eth NIC names, network-scripts, version locks |
Compare with Red Hat's "Preparing a RHEL 8 system for the upgrade" steps |
| Not an inhibitor, but the upgrade fails | Third-party package with the same name as a Red Hat package; MountError with /var/tmp and /var_tmp in /etc/fstab; file systems not shared |
Red Hat's "Known issues" list; the MountError fix and its Risk are under "Known issues to check on VMware guests" |
Prove the cause before changing anything
Run the report as root with the unconfined SELinux role. Red Hat says if you use sudo, add -r unconfined_r -t unconfined_t:
leapp preupgrade --target-version <target_os_version>
Replace the placeholder with a supported target, for example 9.6, as Red Hat does. Without it, Leapp uses the default in the supported-paths table. Options documented for special cases: --enablerepo <repository_id> for custom repositories; --no-rhsm when you do not use Red Hat Subscription Manager or you use RHUI; --channel <channel> with eus, aus or e4s. If you use --channel, use the same value for leapp upgrade.
Then read the results without changing anything. The report is the text file /var/log/leapp/leapp-report.txt. /var/log/leapp/answerfile holds the questions Leapp needs answered. /var/log/leapp/leapp-upgrade.log lists problems from the initramfs phase.
Check free space for the 4 GB the assessment can use:
df -h /var/lib/leapp
Example (illustrative): web01 is RHEL 8.10 on a VMware virtual machine. leapp preupgrade --target-version 9.8 finishes, and the report has one inhibitor, "Missing required answers in the answer file". The answerfile shows the section [check_vdo] and the question "Are all VDO devices, if any, successfully converted to LVM management?" with confirm = commented out. web01 has no VDO volumes, so the administrator may answer True. The space check shows /var/lib/leapp has 6 GB free, so the 4 GB figure is covered (6 − 4 = 2 GB spare). After the answer, the report runs clean.
Fix
Start with a backup. Red Hat says to "have a full system backup or a virtual machine snapshot", and lists ReaR, LVM snapshots, RAID splitting or a snapshot of the whole VM. It adds that LVM snapshots "do not create a full backup of your system", so a full ReaR backup is safer.
Answer the questions Leapp asks
Edit /var/log/leapp/answerfile, delete the # in front of confirm, and set True or False. Alternatively:
leapp answer --section check_vdo.confirm=True
Red Hat's text for this question warns that entering True "will circumvent check of failures and undetermined devices", and that recognised VDO devices not yet converted to LVM "can still block the upgrade." Answer True only when no VDO devices exist or all are converted. Unconverted VDO data would be inaccessible after the upgrade.
Risk: True tells Leapp to skip that check, so a wrong answer can hide a later failure. To back out, change the value and run leapp preupgrade again.
SHA-1 signed packages
Red Hat's instruction: "either remove these packages or contact the vendor for packages with RSA/SHA-256 signatures."
Disruptive step: removing a package removes its files and may stop a service that depends on it. List what requires the package first with dnf repoquery --whatrequires <package> (documented in the DNF command reference). To back out, reinstall the package from a source that supplies a SHA-256 signed build.
Same-name third-party packages
If a package not signed by Red Hat has the same name as a Red Hat package, Red Hat says the upgrade fails. Either remove the third-party package or replace it with the Red Hat one.
Disruptive step: removal may stop a service that depends on the package. Check first. To back out, reinstall it from its source.
Missed preparation steps
Red Hat's preparation list includes: registering with RHSM and enabling rhel-8-for-x86_64-baseos-rpms and rhel-8-for-x86_64-appstream-rpms; subscription-manager release --set 8.10; dnf versionlock clear if the plug-in is used; dnf install leapp-upgrade; dnf update then reboot; stopping client-server configuration management such as Puppet, Salt or Chef until the upgrade completes; disabling antivirus and health checks (including IPMI watchdogs); moving legacy network-scripts to a NetworkManager dispatcher script; and avoiding more than one NIC with a name based on the kernel's eth prefix.
Risk: registering and enabling the two repositories changes the subscription state and the repositories dnf reads. The Red Hat text read gives no command to undo either, so note the enabled repositories first.
Risk: dnf install leapp-upgrade installs the Leapp packages and their dependencies. The Red Hat text read gives no back-out.
Risk: subscription-manager release --set 8.10 pins the system's release version, so later dnf runs take packages for that minor release. Back out by running the same command with the earlier value.
Risk: dnf versionlock clear removes every version lock (the dnf-plugins-core manual says it will "Remove all versionlock entries"), so packages that were pinned for a reason can be updated by the dnf update that follows. Save the list first with dnf versionlock list, which the same manual documents, so that you can recreate the entries with dnf versionlock add.
Risk: stopping Puppet, Salt or Chef means the server is no longer corrected back to its intended configuration while it is stopped, and the same applies to antivirus and health checks you disable (including IPMI watchdogs, which Red Hat says to disable "to prevent the upgrade process from being interrupted"). Back out by enabling each one again once the upgrade is complete (Red Hat says "until after the upgrade is complete"). Record what you disabled so nothing stays off.
Risk: moving network-scripts and writing a NetworkManager dispatcher script changes how the network comes up at boot. A mistake can leave the server without its network after a reboot, so keep a console open. Back out by moving the original scripts back.
Disruptive step: dnf update followed by reboot restarts the server. Plan the outage window, and note that there is no automatic way back; restore from the backup or snapshot.
Known issues to check on VMware guests
Red Hat's known-issues list includes virtual machines created at VMware hardware level 13 that boot with UEFI, which "might experience issues during the upgrade because the NVRAM file is too small." It also says mounted file systems from /etc/fstab that lack the shared propagation flag can make the upgrade fail, and gives mount -o remount --make-shared <mountpoint> for each. The same list names software RAID as a configuration where the upgrade "might fail".
Risk: mount -o remount --make-shared <mountpoint> remounts a live file system with a different propagation setting. Run it one mount point at a time, outside peak load, and check that the services using that mount point still work. Note each mount point's propagation state before you change it. To back out, the mount(8) manual documents mount --make-private mountpoint, which sets the propagation type to private.
For the MountError case with /var/tmp and /var_tmp in /etc/fstab, Red Hat says to unmount the mount point that contains underscore characters and comment it out of /etc/fstab before the upgrade, and that you can restore the configuration after the upgrade.
Risk: unmounting makes that mount point's data unavailable to every service using it, and a wrong /etc/fstab edit can stop the mount returning at boot. To back out, restore the line and mount it again.
Run the report again
After each fix, run leapp preupgrade again. Red Hat's procedure says to repeat until the critical problems are resolved. Only then move to leapp upgrade. If the upgrade is later stopped, Leapp writes the reason to leapp-report.txt.
Start the upgrade
Red Hat's prerequisites are the completed preparation, including a full backup and temporarily disabled health checks, and a report with all issues resolved. Confirm that you can restore the backup or snapshot. Then run leapp upgrade with the same --target-version, --channel, --enablerepo and --no-rhsm options as the pre-upgrade run:
leapp upgrade --target-version <target_os_version>
Disruptive step: after leapp upgrade prepares the transaction, a reboot boots a RHEL 9 initial RAM disk that upgrades all packages and then reboots into RHEL 9. The server is out of service meanwhile, and the packages and kernel change. Plan the outage window and keep a console open. Back out by restoring the backup or reverting the snapshot; there is no way back from a completed upgrade.
Confirm the fix
leapp preupgradefinishes and/var/log/leapp/leapp-report.txtcontains no inhibitor./var/log/leapp/answerfilehas no unanswered questions.- The backup or snapshot exists, and you have confirmed you can restore from it.
- After the upgrade, verify as described in Red Hat's "Verifying the post-upgrade state".
What to watch afterwards
- Red Hat says Leapp sets SELinux to permissive during the upgrade, so re-check it afterwards. For denials Red Hat suggests
ausearch -m AVC,USER_AVC -ts boot,journalctl -t setroubleshootanddmesg | grep -i -e selinux -e type=1400. - Red Hat notes
logrotateis not active after the upgrade; its fix issystemctl enable --now logrotate.timer. Risk: this enables and starts a timer that rotates logs and may delete old log files. To back out, runsystemctl disable --now logrotate.timer(Red Hat gives no back-out). - Services that stop working afterwards, and the default boot entry if the old RHEL 8 kernel still boots.
- Keep the snapshot until the services have run through a full business cycle.
Read next
Related articles you may want next.
- VMwarePlanning a vSphere Major Upgrade: Order, Interoperability and a Go/No-Go RecordPlan a vSphere 7 to 8 upgrade: follow Broadcom's update sequence, check interoperability and upgrade paths, clear removed features, and record a go/no-go decision.Read article
- Backup & RecoveryChecking a restored Linux server against its package records: rpm --verify, dpkg --verify and debsumsUse rpm --verify, dpkg --verify and debsums to check a restored Linux server, read the output, and know what package checks cannot see.Read article
- Troubleshootingdnf "Error: Failed to download metadata for repo": read the reason after the colondnf says Failed to download metadata for repo? The reason after the colon points to a retired repo, empty mirror list, proxy, TLS or cache. Check each.Read article
Risks and limits
- These commands have not been run or lab-tested. They come from Red Hat's guide as captured on 13 June 2026.
- The pre-upgrade report cannot find every problem.
- A snapshot taken before the upgrade protects the disk state only. For servers with databases, take an application-consistent backup as well.
- In-place upgrades of other distributions in the RHEL family, SAP systems and Satellite servers follow different guides.
Sources
- Upgrading from RHEL 8 to RHEL 9 — Red Hat documentation, no date shown; Internet Archive copy of 13 June 2026, accessed 18 November 2026
- df(1) — GNU coreutils 9.11 (page obtained 2026-08-03), accessed 18 November 2026
- mount(8) — util-linux project, page obtained 2026-08-04, accessed 18 November 2026
- versionlock plugin — DNF plugins core documentation, copyright 2014, no date shown, accessed 18 November 2026
This article was originally published on .