WordPress failure signatures

When WordPress breaks, the server usually still sends something back, sometimes even with a status that says all is well. A simple uptime monitor sees an answer and calls the site up. This rule set reads the page itself and recognises the screens WordPress, PHP and plugins show when something went wrong. On Checks & pages it shows as WordPress errors.

What WP Moo looks at

"Error establishing a database connection".
The WordPress install or setup screen, which WordPress shows when it can't find its database tables or its wp-config.php.
"There has been a critical error on this website", or the older wording "The site is experiencing technical difficulties".
"Briefly unavailable for scheduled maintenance", the screen WordPress shows while it installs updates.
A PHP fatal, parse or recoverable error printed in the page, also in the table Xdebug prints on a development server.
PHP warnings, notices and deprecations for a file of WordPress, a plugin or a theme, also in Xdebug's table (a path with /wp-content/, /wp-includes/ or /wp-admin/, or a WordPress file like wp-config.php).
A blank page: smaller than 2 KB, the classic white screen.
A maintenance or coming-soon plugin page, on pages search engines should find.

Dutch WordPress sites are recognised too. We match the error screen's own markup, so a blog post that mentions a database or critical error passes. A post that pastes a full PHP error on a line of its own can still be caught.

Everything here is Urgent and takes the page offline once a second check confirms it. PHP warnings, notices and deprecations are the exception: they are Important, because visitors still get the page.

What the problems mean

The page shows a database error "Error establishing a database connection" Urgent The database server is usually down or overloaded, or its password changed. Ask your host whether the database server is running.

The page shows the WordPress install screen WordPress install or setup screen Urgent Restore the database or wp-config.php from a backup right away, or ask your host whether the database was emptied or moved.

The page shows a critical error "There has been a critical error on this website" Urgent This is usually a plugin or theme update that went wrong. WordPress emails a recovery link to the admin address; use it to switch the plugin off.

The page is stuck in maintenance mode "Briefly unavailable for scheduled maintenance" Urgent An update probably stopped halfway. Delete the .maintenance file in the WordPress folder, then check that the update finished.

The page shows a PHP error PHP fatal, parse or recoverable error in the page Urgent The error names the plugin or theme file that failed. Switch that plugin off until it's fixed.

The page shows PHP warnings PHP warnings, notices or deprecations from WordPress files Important The message names the file, and with it the plugin or theme behind it. Update or fix that one, and turn off display_errors on the live site.

The page is blank White screen: page smaller than 2 KB Urgent This is usually a PHP error that isn't shown. Check the PHP error log on the server.

The page shows a coming-soon page Maintenance or coming-soon plugin page Urgent Switch the plugin's maintenance mode off if the site should be live.

What each priority means: Problem priority.

How to fix it

Database error

The database server is usually down or overloaded, or its password changed. Ask your host whether the database server is running.

Install screen

Act now: anyone who opens the site can finish the install and take it over. The database is usually emptied, moved or switched to another one, or wp-config.php is missing. Restore the database or wp-config.php from a backup, or ask your host what changed. Don't fill in the install screen yourself: that makes a new, empty site.

Critical error or PHP error

Usually a plugin or theme update that went wrong. WordPress emails a recovery link to the site's admin address; use it to log in and switch the plugin off. A PHP error names the file that failed, which tells you the plugin or theme. Not sure? Forward the problem to your developer.

Stuck in maintenance

An update stopped halfway. Delete the .maintenance file in the WordPress folder on the server, then check in WordPress that the update finished.

Blank page

Almost always a PHP error that isn't shown. Check the PHP error log in your hosting panel, or forward it to your developer.

Coming-soon page

Switch the plugin's maintenance or coming-soon mode off if the site should be live. Is the page meant to stay out of sight? Set its Search engines setting to Hidden in Checks & pages, and this rule leaves it alone. Don't check isn't enough: it only stops the Search engines rules, and this rule still runs.

PHP warnings

Notices and deprecations get the same fix as warnings. The message names the file, and with it the plugin or theme behind it. A notice from a file in /wp-includes/ is usually about a plugin or theme too: the message names it, like the "Translation loading … was triggered too early" notice since WordPress 6.7. Update that plugin or theme, or ask your developer to fix it and to turn off display_errors on the live site.

For your developer

The signatures are regular expressions on the first 512 KB of the decoded body, anchored on the markup of the error page together with its English or Dutch text: the wp-die-message container of wp_die(), or the <h1> of WordPress's bare database error page. In other languages these screens don't match, and the page fails on its 500 or 503 status instead. The install screen matches on the stylesheet WordPress's setup screens load (/wp-admin/css/install.min.css, or its -rtl or unminified version) together with the setup form (<form id="setup") or the link to setup-config.php?step=1, which are the same in every language. The database update screen after a WordPress update loads the same stylesheet without them, so it passes.

A PHP error ("Fatal error", "Parse error", "Recoverable fatal error" or, before PHP 7.1, "Catchable fatal error") only matches with the "in /path/file.php on line N" tail, or a stack trace, that PHP always prints. Xdebug's error table matches on its xdebug-error class with xe-fatal-error, xe-recoverable-fatal-error, xe-parse-error or xe-uncaught-exception. A "Warning", "Notice" or "Deprecated" matches in PHP's HTML or plain format, or in Xdebug's table, when its "in FILE on line N" part names a path under /wp-content/, /wp-includes/ or /wp-admin/ (with forward or back slashes), or a wp-*.php file in the WordPress folder such as wp-settings.php, within 1,500 characters of the message.

The white screen rule counts the decoded body of HTML answers (or answers without a Content-Type) only, so a small sitemap or feed passes, and skips answers with a status of 400 or higher, which fail on their status already. The coming-soon rule needs a robots noindex meta tag plus a file from a known plugin's folder (SeedProd, WP Maintenance Mode, CMP, Under Construction and a few others), and doesn't run on pages set to Hidden.

Something unclear on this page? Email [email protected]