Troubleshoot GPG Check FAILED Error in Linux: A Comprehensive Guide

When attempting to install or update software packages in a Red Hat-based Linux distribution like CentOS, AlmaLinux, or Fedora using the yum or dnf package manager, encountering a “GPG check FAILED” error can be a frustrating roadblock.

This error signifies that the system cannot verify the authenticity and integrity of the software package you are trying to install.

This article provides a complete guide to understanding and resolving this common issue, ensuring your system remains both secure and up-to-date.

Understanding the Role of GPG Checks

GPG (GNU Privacy Guard) keys are a fundamental aspect of Linux security. They are used to sign software packages, creating a digital signature that can be verified by the package manager. This verification process ensures two critical things:

• Authenticity: It confirms that the package you are installing was created by the legitimate developer or distributor and has not been replaced by a malicious third party.
• Integrity: It guarantees that the package has not been tampered with or corrupted since it was signed.

When yum or dnf downloads a package, it also retrieves the corresponding GPG signature. It then checks this signature against the public GPG key of the repository from which the package was downloaded. If the check fails, the installation is halted to protect your system from potentially harmful software.

Common Causes of the “GPG check FAILED” Error

Several factors can lead to a GPG check failure:

• Missing GPG Key: The necessary public GPG key for the repository is not installed on your system.
• Outdated GPG Key: The repository has updated its GPG key, and your system is still using an old, expired, or revoked key.
• Corrupted GPG Key: The GPG key file on your system may have become corrupted.
• Corrupted yum Cache: The cached package data or metadata might be corrupted, leading to verification failures.
• Network Issues: Problems during the download process can result in a corrupted package or signature file.
• Incorrect Repository Configuration: The repository configuration file may point to an incorrect GPG key location.

How GPG Keys Work in RPM

When you install software on an RPM-based Linux system (like RHEL, AlmaLinux, or CentOS), the package manager wants to make sure that the file you’re installing is authentic and hasn’t been tampered with.

That’s where GPG keys come in.

1. Package Signing
   • The software vendor builds an RPM package and then signs it using their private GPG key.
   • This creates a cryptographic signature that gets embedded in the RPM file.
2. Key Importing
   • On your system, you import the vendor’s public GPG key using a command like:
     

     rpm --import <https://vendor.com/path/to/public.key>
     

     
     
   • When you do this, RPM stores the key in its database as a special “virtual package” named like:
     

     gpg-pubkey-<KEYID>-<TIMESTAMP>
     

     
     

     It’s not a real package — it contains no files — it’s just metadata that allows RPM to verify signatures.

3. Verification During Install
   • When you install a package, RPM extracts the signature from the RPM file.
   • It then uses the stored public key to check that:
     • The package was signed by the expected vendor.
     • The contents haven’t been altered since it was signed.
4. GPG Check Failures
   • If the package’s signature doesn’t match any imported public key, or if the key is wrong/expired, you’ll see an error like:
     

     GPG check FAILED
     

     
     

     This means RPM refuses to install it until the correct key is imported.

     See also: Mastering the Linux Command Line — Your Complete Free Training Guide

---

💡 In short:

• Private key → used by the vendor to sign packages.
• Public key → imported into your system to verify those signatures.
• RPM treats public keys like “virtual packages” so they can be listed and removed just like normal software, but they’re really just stored verification data.

How to Remove an Existing or Outdated GPG Key

Before importing a new key, it’s sometimes necessary to remove an old, incorrect, or outdated one that is causing the conflict. GPG keys are managed by the RPM package manager as special packages named gpg-pubkey.

Step 1: List all installed GPG keys

To see all the GPG keys currently trusted by your system’s RPM database, use the following command. The custom query format (--qf) provides a clean, human-readable list.

rpm -q gpg-pubkey --qf '%{NAME}-%{VERSION}-%{RELEASE}\\\\t%{SUMMARY}\\\\n'

The output will look something like this:

gpg-pubkey-f4a80eb5-53a7ff4b    gpg(CentOS-7 Key (CentOS 7 Official Signing Key) <[email protected]>)
gpg-pubkey-352c64e5-52ae6884    gpg(Fedora EPEL (7) <[email protected]>)

Step 2: Identify and Remove the Correct Key

From the list, identify the key that corresponds to the repository causing the error. The name of the key is in the first column (e.g., gpg-pubkey-352c64e5-52ae6884).

Use the rpm -e command to remove the key, treating it just like any other package.

sudo rpm -e gpg-pubkey-352c64e5-52ae6884

Replace gpg-pubkey-352c64e5-52ae6884 with the name of the key you wish to remove. After removing the old key, you can proceed with importing the new, correct key.

Step-by-Step Solutions to Fix the GPG Check FAILED Error

Here are several methods to resolve the “GPG check FAILED” error, ordered from the most recommended and secure to the least.

Solution 1: Import the Correct GPG Key

The most common and secure solution is to import the correct GPG key for the repository in question.

1. Find the GPG Key URL: The repository’s official website or documentation should provide the URL for their GPG public key. This is often found in the installation instructions. For instance, the command to import the key for AlmaLinux is rpm --import <https://repo.almalinux.org/almalinux/RPM-GPG-KEY-AlmaLinux>.
2. Import the Key: Use the rpm --import command to add the key to your system’s keyring.
   

   sudo rpm --import <URL_of_GPG_key>
   
   

   
   

   For example, to import the EPEL (Extra Packages for Enterprise Linux) 8 GPG key, you would use:

   
   

   sudo rpm --import <https://dl.fedoraproject.org/pub/epel/RPM-GPG-KEY-EPEL-8>
   

   
   

   (Note: The specific URL and key name may vary depending on your distribution and the repository.)

3. Retry the Installation: After importing the key, try running your yum install or dnf install command again.

Solution 2: Clean the yum or dnf Cache

A corrupted or outdated cache can cause GPG check failures. Clearing the cache forces the package manager to download fresh metadata and package information.

1. Clean the Cache: Execute the following command to remove all cached files from enabled repositories.
   

   sudo yum clean all
   
   

   
   

   or for dnf:

   
   

   sudo dnf clean all
   ```    This command is generally sufficient and safe to run.
   
   

   
   
2. Rebuild the Cache (Optional): You can then have yum or dnf rebuild the cache:
   

   sudo yum makecache
   
   

   
   

   or for dnf:

   
   

   sudo dnf makecache
   
   

   
   
3. Retry the Installation: Attempt the package installation again.

Solution 3: Update Repository Release Packages

Sometimes, GPG keys are updated as part of a repository’s release package (e.g., almalinux-release, epel-release). Upgrading this package can resolve key-related issues.

sudo dnf upgrade <repository-release-package>

Solution 4: Verify and Correct Repository Configuration

Ensure that the repository configuration file points to the correct GPG key. Repository files are located in the /etc/yum.repos.d/ directory.

1. Inspect the Repository File: Open the relevant .repo file with a text editor.
2. Check the gpgkey Directive: Look for the gpgcheck=1 line, which enables the GPG check, and the gpgkey= line, which specifies the location of the GPG key.
   

   [epel]
   name=Extra Packages for Enterprise Linux 8 - $basearch
   baseurl=http://download.fedoraproject.org/pub/epel/8/$basearch
   enabled=1
   gpgcheck=1
   gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL-8
   
   

   
   

   Verify that the gpgkey URI is correct and points to a valid key file.

Solution 5: Rebuild the RPM Database

In rare cases, the RPM database itself might have issues. Rebuilding it can resolve these problems.

sudo rpm --rebuilddb

Solution 6: Temporarily Disable the GPG Check (Use with Caution)

If you are certain that the package you are installing is from a trusted source and you need to bypass the GPG check as a temporary measure, you can do so. However, this is not recommended for production systems as it exposes you to security risks.

You can disable the GPG check in a few ways:

• For a single command: Use the -nogpgcheck flag with your yum or dnf command.
  

  sudo yum install --nogpgcheck <package_name>
  
  

  
  
• For a specific repository: Edit the corresponding .repo file in /etc/yum.repos.d/ and change gpgcheck=1 to gpgcheck=0. This will permanently disable the GPG check for that repository.
• Globally (Strongly Discouraged): You can disable GPG checks for all repositories by setting gpgcheck=0 in the [main] section of /etc/yum.conf or /etc/dnf/dnf.conf. This is a significant security risk and should be avoided.

Conclusion

The “GPG check FAILED” error is a protective measure designed to safeguard your system.

By following the troubleshooting steps outlined in this guide—from removing old keys to importing new ones and maintaining a clean package manager cache—you can effectively diagnose and resolve the underlying issue.

Always prioritize using valid GPG keys to ensure the security and integrity of your Linux system. While disabling the GPG check can be a quick workaround, it should be used sparingly and with a clear understanding of the associated risks.