Chapter 7. Troubleshooting
This chapter lists troubleshooting resources and tips.
7.1. Troubleshooting resources
By default, only error and critical log level messages are printed to the console output by the
Leapp utility. To change the log level, use the
--debug options with the
leapp upgrade command.
In verbose mode,
Leappprints info, warning, error, and critical messages.
In debug mode,
Leappprints debug, info, warning, error, and critical messages.
/var/log/leapp/leapp-upgrade.logfile lists issues found during the initramfs phase.
/var/log/leapp/dnf-debugdata/directory contains transaction debug data. This directory is present only if the
leapp upgradecommand is executed with the
journalctlutility provides complete logs.
/var/log/leapp/leapp-report.txtfile lists issues found during the pre-upgrade phase. The report is also available in the web console, see Section 3.2, “Assessing upgradability and applying automated remediations through the web console”.
7.2. Troubleshooting tips
- Verify that your system meets all conditions listed in Chapter 1, Planning an upgrade.
Make sure you have followed all steps described in Chapter 2, Preparing a RHEL 7 system for the upgrade, for example, your system does not use more than one Network Interface Card (NIC) with a name based on the prefix used by the kernel (
Make sure you have resolved all problems identified in the pre-upgrade report, located at
/var/log/leapp/leapp-report.txt. To achieve this, you can also use the web console, as described in Section 3.2, “Assessing upgradability and applying automated remediations through the web console”.
If a problem occurs during downloading RPM packages, examine transaction debug data located in the
During this phase, potential failures redirect you to the Dracut shell. Check the Journal log:
Alternatively, restart the system from the Dracut shell using the
rebootcommand and check the
- If your system seems to be successfully upgraded but booted with the old RHEL 7 kernel, restart the system and check the kernel version of the default entry in GRUB.
- Make sure you have followed the recommended steps in Chapter 5, Verifying the post-upgrade state of the RHEL 8 system.
If your application or a service stops working or behaves incorrectly after you have switched SELinux to enforcing mode, search for denials using the ausearch, journalctl, or dmesg utilities:
# ausearch -m AVC,USER_AVC -ts boot # journalctl -t setroubleshoot # dmesg | grep -i -e selinux -e type=1400
The most common problems are caused by incorrect labeling. See Troubleshooting problems related to SELinux for more details.
7.3. Known issues
- Network teaming currently does not work when the in-place upgrade is performed while Network Manager is disabled or not installed.
If you use an HTTP proxy, Red Hat Subscription Manager must be configured to use such a proxy, or the
subscription-managercommand must be executed with the
--proxy <hostname>option. Otherwise, an execution of the
subscription-managercommand fails. If you use the
--proxyoption instead of the configuration change, the upgrade process fails because
Leappis unable to detect the proxy. To prevent this problem from occurring, manually edit the
rhsm.conffile as described in How to configure HTTP Proxy for Red Hat Subscription Management. (BZ#1689294)
If your RHEL 7 system is installed on an FCoE Logical Unit Number (LUN) and connected to a network card that uses the
bnx2fcdriver, the LUN is not detected in RHEL 8 after the upgrade. Consequently, the upgraded system fails to boot. (BZ#1718147)
If your RHEL 7 system uses a device driver that is provided by Red Hat but is not available in RHEL 8,
Leappinhibits the upgrade. However, if the RHEL 7 system uses a third-party device driver that is not included in the list of removed drivers (located at
Leappdoes not detect such a driver and proceeds with the upgrade. Consequently, the system might fail to boot after the upgrade.
You cannot perform an in-place upgrade when the
winsSamba modules are used in the
/etc/nsswitch.conffile at the moment. The upgrade transaction fails with the following error messages and
Leappinhibits the upgrade:
upgrade: STDERR: upgrade: Error in PREIN scriptlet in rpm package unbound-libs upgrade: Error: Transaction failed upgrade: Container el8userspace failed with error code 1. unbound-libs has a PREIN failure
To work around this problem, configure the system so that it uses only local providers for the
hostsdatabase during the update:
Open the system
/etc/nsswitch.confconfiguration file and search for entries that contain the
If you find such entries, create a backup of
winsfrom the entries that contain them.
- Perform an in-place upgrade.
After the upgrade, add the
winsstrings to the respective entries in
/etc/nsswitch.conf, based on your system configuration requirements.
- Open the system
Leapputility does not change customized authentication configuration during the upgrade process. If you used the deprecated
authconfigutility to configure authentication on your RHEL 7 system, authentication on RHEL 8 might not work correctly. To ensure that your custom configuration functions properly on the RHEL 8 system, re-configure your RHEL 8 system with the
During the in-place upgrade, the deprecated
pam_pkcs11pluggable authentication modules (PAM) are removed. Consequently, if the PAM configuration on your RHEL 7 system contains the
pam_pkcs11modules and if these modules have the
requisitecontrol values, performing the in-place upgrade might result in locking you out of the system. To work around this problem, reconfigure your RHEL 7 system to not use
pam_pkcs11before you start the upgrade process.
On IBM Z systems,
Leappalways expects a DASD disk attached. Consequently, if the
/etc/dasd.conffile does not exist, the in-place upgrade fails. To work around this problem, create an empty
dasd.conffile by using the
touch > /etc/dasd.confcommand. (BZ#1783248)
If a name of a third-party package (not signed by Red Hat) installed on your system is the same as of a package provided by Red Hat, the in-place upgrade fails. To work around this problem, choose one of the following options prior to upgrading:
- Remove the third-party package
- Replace the third-party package with the package provided by Red Hat
During an in-place upgrade, the
dockerpackage is removed without a warning. If you use containers in RHEL, migrate to Podman prior to upgrading to RHEL 8. (BZ#1858711)
7.4. Obtaining support
To open a support case, select RHEL 8 as the product, and provide a
sosreport from your system. To generate a
sosreport on your system, run:
Note that you can leave the case ID empty.
For details on generating a sosreport, see the solution What is an sosreport and how to create one in Red Hat Enterprise Linux?.
For more information on opening and managing a support case on the Customer Portal, see the article How do I open and manage a support case on the Customer Portal?.