1. Introduction
When upgrading cPanel & WHM to a newer version—or installing it on a fresh server—the system performs compatibility checks before starting the upgrade. If any issue is detected that prevents the upgrade, it is classified as an Upgrade Blocker.
There are two types of checks:
- Standard checks: Always performed for all versions.
- Version‑specific checks: Only applied to the version you are upgrading to.
If a blocker is detected:
- The upgrade stops immediately.
- The server remains on the current version.
- A detailed report is emailed to the root administrator.
- The issue is logged in
/usr/local/cpanel/logs/error_log.
2. Critical Warnings Before Any Upgrade
- You must have at least 5 GB of free space in
/usr/local/cpanel. - If you are using unmanaged FTP, switch it back to managed mode:
WHM → FTP Server Configuration → Package Management → Managed- After upgrading, downgrading is not supported.
3. Multi‑Stage Upgrades (Multiple Major Versions)
If the version gap between your current version and the target version is large, cPanel performs the upgrade in multiple stages.
Example:
Current version: 80
Target version: 86
Upgrade path: 80 → 82 → 84 → 86
Each stage performs its own compatibility checks. If any stage fails, the upgrade stops at the last compatible version.
Note: If your server is running a very old version (below 90), it is recommended to manually upgrade to an intermediate version first by editing /etc/cpupdate.conf.
4. Standard Checks (Always Performed)
| Check | Description | Solution |
|---|---|---|
| Valid license file | The license must be valid and readable. | Run /usr/local/cpanel/cpkeyclt or renew the license. |
| Filesystem not read‑only | Critical directories must not be mounted as read‑only. | Remount filesystem as rw or fix disk issues. |
| RPM database health | On non‑Ubuntu systems, the RPM database must be healthy. | Run rpm --rebuilddb or test with yum. |
5. Version‑Specific Upgrade Blockers
The table below lists the most important blockers for versions 110–130:
| cPanel Version | Blocked OS / Issue | Solution |
|---|---|---|
| 134+ | Rocky Linux 8 & 9 | Migrate to AlmaLinux 9 or Rocky Linux 9.5+ |
| 132 | MySQL 5.5 / 5.6 (including remote) | Upgrade to MySQL 5.7+ or MariaDB |
| 132 | AlmaLinux 9 / Rocky 9 / CloudLinux 9 must be 9.5+ | Update OS to 9.5+ |
| 120 | Ubuntu 20.04 | Migrate to Ubuntu 22.04 LTS |
| 112 | Rocky Linux 8 & 9 | Migrate to a supported OS or AlmaLinux |
| 102 | CentOS 8 (EOL) | Migrate to AlmaLinux 8 or Rocky 8 |
| 98–100 | Ubuntu 20.04 (support dropped) | Upgrade to a newer version |
| 88–90 | CentOS 7, CloudLinux 6/7, RHEL 7 | Migrate to a modern OS |
| 86–88 | Amazon Linux 1, CentOS 6, RHEL 6 | Immediate migration required |
| 78 | EasyApache 3 | Migrate to EasyApache 4 |
| 68 | LiteSpeed older than 5.2.1 build 2 | Update LiteSpeed |
| 58 | 32‑bit OS, Amazon Linux 1, CentOS 5 | Migrate to a 64‑bit modern OS |
| 52 | MySQL 5.1 or older | Upgrade to MySQL 5.5+ or MariaDB |
6. Final Recommendations
- Ensure at least 5 GB free space in
/usr/local/cpanel. - Always take a full backup before upgrading:
WHM → Backup → Backup Configuration- Make sure your license is valid.
- Switch unmanaged services (like FTP) back to managed mode.
- For multi‑stage upgrades, let the system handle each step automatically.
- If you encounter a blocker, fix it first, then run:
/scripts/upcp --force- If your version is very old (below 100), upgrade to an intermediate version first.
Conclusion
Upgrade Blockers are essential safeguards that prevent incomplete or unstable installations. Understanding these blockers—and resolving them before upgrading—ensures a smooth, reliable upgrade process and keeps your server stable and secure.