Fix cPanel Update Errors on AlmaLinux and CentOS

Keeping cPanel updated is essential for maintaining server security, performance, and compatibility. However, server administrators occasionally run into frustrating update failures when executing the cPanel update script, commonly known as upcp. These interruptions can be caused by stale lock files, broken package manager dependencies, or underlying issues with the operating system.

If you manage a web hosting server running on AlmaLinux or CentOS, knowing how to systematically diagnose and resolve these roadblocks will save you hours of downtime. In this guide, we will walk through the step-by-step process of troubleshooting and fixing the most common cPanel update failures.

Understanding the cPanel Update Process (upcp)

The /usr/local/cpanel/upcp script is responsible for updating cPanel & WHM, along with its extensive ecosystem of modules, PHP versions, and system packages. When you run upcp, cPanel checks for a lock file to ensure multiple update instances do not run simultaneously. It then queries the operating system's package manager—DNF on AlmaLinux or YUM on older CentOS installations—to pull in required system updates.

When an update fails, it is usually because the process hit a wall it could not bypass automatically. This might be a leftover lock file from a previously crashed update, a conflict in the system package repository, or a corrupted database. Before making any changes, log in to your server via SSH as the root user. The steps and commands in this guide apply to AlmaLinux (versions 8 and 9) and CentOS (versions 7 and 8).

1. Clearing Stale Lock Files

One of the most frequent reasons for an upcp failure is a stale lock file. If a previous update attempt was interrupted by a network drop, a server reboot, or a manual cancellation, cPanel may leave a lock file behind. When this happens, subsequent update attempts will immediately abort with a message stating that an update is already in progress.

To check if a cPanel update process is genuinely running, you can inspect the process list or simply look for the lock file. For AlmaLinux and CentOS systems, cPanel uses specific lock files in the filesystem.

Run the following command to check for running cPanel update processes:

ps aux | grep upcp

If the output only shows your grep command, no update is running. You can safely remove the stale lock files using these commands:

rm -f /var/cpanel/updatelock
rm -f /usr/local/cpanel/logs/upcp.lock

The rm -f command forces the deletion of the specified lock files without asking for confirmation. Once removed, you can re-run your update safely.

2. Resolving Broken RPM and Package Manager Dependencies

Because cPanel relies heavily on the underlying Linux distribution's package manager, issues with RPM databases or broken repository dependencies will inevitably break upcp. On AlmaLinux 8/9 and CentOS 8, package management is handled by DNF, while CentOS 7 relies on YUM.

If system packages are out of sync or if a third-party repository has conflicting versions, the update script will fail when trying to update system dependencies.

First, test your system package manager independently of cPanel to see if there are underlying dependency problems. For AlmaLinux or CentOS 8/9, run:

dnf check

If you are on CentOS 7, run:

yum check

If this command reports broken dependencies, missing packages, or duplicate entries, you must resolve them before cPanel can update successfully. Common fixes include cleaning the package manager cache and fixing transaction issues.

Clean all cached package data on AlmaLinux or CentOS 8/9:

dnf clean all
dnf makecache

If you encounter a corrupted RPM database (often throwing errors about mismatched database versions), you can rebuild the RPM database on your AlmaLinux/CentOS server with these commands:

rm -f /var/lib/rpm/__db*
rpm --rebuilddb

The rm -f command clears out any corrupted database lock files, and rpm --rebuilddb rebuilds the database indexes from scratch.

3. Fixing Disk Space and Inode Exhaustion Issues

An update failure can occasionally be deceptive, masquerading as a dependency or script error when the root cause is simply a lack of disk space or available inodes on the server.

cPanel updates download numerous packages, compile software, and write extensive log files. If your root partition (/) runs out of space mid-update, files become truncated or corrupted.

Check your current disk space usage across all mounted filesystems:

df -h

Check your inode usage to ensure you haven't run out of file identifiers (common on servers with millions of small files like emails or cache directories):

df -i

If the root partition is at full capacity, free up space by cleaning old package caches, clearing out old logs in /var/log/, or removing temporary files before attempting the update again.

4. Running and Debugging upcp Manually

When automated updates fail in WHM, running the update script manually via the SSH command line provides real-time visibility into errors. It allows you to see the exact moment the script halts and read the associated error stack trace.

To run the cPanel update script with verbose logging enabled on your AlmaLinux or CentOS server, use:

/usr/local/cpanel/upcp --verbose

The --verbose flag forces the script to output detailed operational steps directly to your terminal screen. If the script fails, examine the tail end of the output or check the dedicated update log file located at:

/var/log/cpanel/upcp.log

You can view the last 100 lines of the update log using the following command:

tail -n 100 /var/log/cpanel/upcp.log

Reading through this log will usually pinpoint the exact service, Perl module, or RPM package that triggered the failure.

Conclusion

Troubleshooting cPanel update failures on AlmaLinux and CentOS requires a methodical approach. By systematically clearing stale lock files, verifying and repairing the system package manager and RPM database, ensuring adequate disk space, and reading the verbose logs, you can resolve the vast majority of upcp errors.

If you encounter persistent dependency errors tied to custom third-party repositories or operating system core libraries, address those conflicts individually before re-initiating the cPanel update process. Keeping your server environment clean and updated ensures your hosting infrastructure remains stable and secure.