Introduction
Several situations could occur to cause cPanel & WHM update failures. Update failures not only prevent you from using the best version of cPanel available for your update tier but may prevent critical security updates from being applied, leaving your server vulnerable to known attack vectors.
This article will help you find the error message so that you can proceed to research it.
Important files and directories
Directory: /var/cpanel/updatelogs
You will find most of the files you need to diagnose update errors in the /var/cpanel/updatelogs directory. It has the following important files:
- The last update log at /var/cpanel/updatelogs/last - This symbolic link (symlink) points to the log for the last attempted update.
- The summary log at /var/cpanel/updatelogs/summary.log - This log file records the date that version changes occurred.
- Multiple individual update logs named like update.[0-9]{10}.log - The regular expression "[0-9]{10}" means a number between 0 and 9, repeated ten times (a ten-digit number).
For example, running the command "ls -lah /var/cpanel/updatelogs/" gets the following output on my test server:
-bash-4.2# ls -lah /var/cpanel/updatelogs/
total 2.9M
drwx------ 2 root root 4.0K Jul 23 00:13 .
drwx--x--x 107 root root 8.0K Jul 23 00:43 ..
lrwxrwxrwx 1 root root 44 Jul 23 00:13 last -> /var/cpanel/updatelogs/update.1595481181.log
-rw------- 1 root root 672 Jul 21 00:13 summary.log
-rw------- 1 root root 45K Jun 9 00:13 update.1591679581.log
-rw------- 1 root root 45K Jun 10 00:13 update.1591765981.log
... output cut off ...
File: /usr/local/cpanel/logs/error_log
Despite its name, this log file records many types of messages (not just errors) and may have supplemental information that is helpful when diagnosing update issues.
Procedure
The easiest way to find an error message in an update log is to search for " E " using a utility called grep. The command looks like this:
grep " E " /var/cpanel/updatelogs/update.1234567890.log
Sometimes this simple method does not show you the entire failure message or returns nothing (even when a failure occurs). In those cases, you need to skim through the log file to detect errors manually. The best tool to view a large file that you do not want to change is called less. The command looks like this:
less /var/cpanel/updatelogs/update.1234567890.log
Most of the lines in the update logs contain a timestamp at the start of the line. A timestamp tells you when the event occurred to allow cross-referencing with other logs, like the cPanel error log. The cPanel update logs and the cPanel error log all show the date format as "YYYY-MM-DD hh:mm:ss timezone". An example of this format is [2020-07-23 00:14:22 -0500]. Ensure that the timezone is the same in both logs to guarantee that you view the same point in time when matching up the timestamps. It should be, but it's a good idea to habitually check since some logs will use UTC (and show an offset of 0000 regardless of the server's timezone).
If you need to look in the cPanel error log for update errors, you will use the less command to open the log file and then find the correct time frame by reviewing the timestamps. Sometimes the update log will have a line with a timestamp like [2020-07-23 00:14:25 -0500] with the next line reading [2020-07-23 00:16:02 -0500]. The line in the cPanel error log could start with anything in between those two - so if there's a message at [2020-07-23 00:15:46 -0500], it could be relevant.
Once you find the error message, you will need to research it to find a solution. Search this knowledge base for keywords first. If you don't see anything relevant, try checking our documentation at https://docs.cpanel.net. If documentation on the issue does not exist, look in our forums at https://forums.cpanel.net. Maybe someone has posted a similar problem with a solution. When checking the forums, please be careful not to run commands unless you know what they do (especially if the post is more than a year old). Of course, we are always here to help too!