hostdoc — offline cPanel/WHM/WHMCS support brain

← all runbooks

---
title: WordPress site is broken after an update
panel: cPanel
symptoms:
  - white screen
  - fatal error
  - site shows an error after updating a plugin
  - database error on the front end
  - wordpress shows a white screen
  - fatal error allowed memory size exhausted
  - site is blank after a plugin update
  - wordpress database error
  - wp-admin will not load
  - the front end of the site is blank
---

# WordPress site is broken after an update

## 1. Get the actual error out of the white screen

**Why:** a blank page hides the message, and the message is the entire
diagnosis. WordPress also has a recovery mode that puts the site back
into a working state with plugins disabled, which turns an outage into a
diagnosis rather than a firefight.

**In the terminal:** `tail -50 /home/<user>/logs/<domain>.error_log` for
the PHP fatal error, which names the file and the line.

**In cPanel:** Metrics > Errors shows the same errors from the panel.

**Care:** this only reads.

## 2. Isolate the plugins

**Why:** if the site comes back with plugins disabled, the fault is in a
plugin and you know where to look. Renaming them back one at a time
finds which one, and it keeps the cause. Updating everything at once
destroys the evidence and leaves the customer with a site that is
different from the one they had.

**In cPanel:** Files > File Manager. Rename the `plugins` directory in
`public_html/wp-content` to `plugins.off` and reload the site.

**In the terminal:** `mv ~/public_html/wp-content/plugins ~/public_html/wp-content/plugins.off`

**Care:** the site stays broken but with plugins off, so the customer
still cannot trade. Tell them what you are doing and how long it will
take. Rename the directory back before you finish.

## 3. Check the PHP version

**Why:** an update can need a newer PHP than the account is running, and
that gives a parse error on a line that is perfectly valid on a newer
version. The error looks like broken code and is actually a version
mismatch, which is a completely different fix and one you can make
without touching the site.

**In cPanel:** Software > Select PHP Version.

**In the terminal:** `php -v` and check what the plugin's readme says it
needs.

**Care:** raising the PHP version can break a site that was working on
the old one. Check what else on the account depends on it first.

- https://docs.cpanel.net/knowledge-base/general-systems-administration/cpanel-php/

## 4. Check the database

**Why:** "Error establishing a database connection" on every page looks
like a catastrophic site failure and is usually a database user whose
grant is missing, or a password that changed in the config but not in the
database. It takes two minutes to check and it is very common after a
hosting migration.

**In cPanel:** Databases > Manage My Databases shows the users and what
each one is granted access to.

**In the terminal:** `mysql -u <dbuser> -p -e "SHOW DATABASES;"` and
compare the database name in `wp-config.php` with what is there.

**Care:** read only. If you change a database password you have to change
it in the config file in the same minute, or the site stays down.

- https://docs.cpanel.net/cpanel/databases/manage-my-databases/
- https://docs.cpanel.net/knowledge-base/sql/how-to-restore-a-user-database-access/