This blog post will be somewhat different from what I usually write for my column at WPX. For starters, it will be shorter than the average, which — as the WPX team has delicately tried to suggest on more than a few occasions already — might not be that bad by itself.
But more importantly, this column is not structured as a solution for a specific problem. Instead, it shows how a bit of recently added functionality actually makes it more difficult to diagnose and fix WordPress runtime errors and tells you how to overcome this unhelpful behavior as you rush to fix things.
I will share with you the SOP (standard operating procedure) I follow when I have to fix an issue that has caused the appearance of the infamous “There has been a critical error on this website” message. It is not a solution for any specific issue; it is simply the first step one must take to understand why their WordPress website broke.
I will be referring to this SOP many times in later blog posts, so I might just as well put this article up first. Hence, the whole raison d’être for today’s column.
The Site is Experiencing Technical Difficulties — But Why?
WordPress is built using the PHP programming language. Like most modern programming languages for the web, PHP is what we call a scripting (the more technical term is ‘interpretative’) language.
In very simplistic terms, you can think of PHP code as a theatrical script. At the beginning of the performance, the audience does not know what will happen. Only as the actors come on the set and begin doing their stuff, the story begin to unravel. If something unplanned happens — say, the lead hurts his knee while lunging to save his love interest during the second act and can’t continue, there is no elegant way to end the performance.
For the longest time, WordPress handled errors like theatrical directors handled botched live performances: inelegantly. Unexpected events would cause weird error messages to appear on the screen. Sometimes the browser window itself would become completely blank, which became popular as the “WordPress White Screen of Death”.
The “Fix”
As part of the 5.2 release, the WP Core dev team shipped a feature called “PHP Error Protection” which intended to end this. In the words of WP Core,
This administrator-focused update will let you safely fix or manage fatal errors without requiring developer time. It features better handling of the so-called “white screen of death,” and a way to enter recovery mode, which pauses error-causing plugins or themes.
Once you have upgraded to WordPress 5.2 and ever since, a broken WordPress instance will no longer show a blank or a weird-looking page upon hitting a PHP error, but instead will show a polite notice that something is wrong.
Your visitors will see a “The site is experiencing technical difficulties” when they access public-facing pages. Users who try to access the back-end will see a second line: “Please check your site admin email inbox for instructions.”
WordPress will also send a message to the site admin email address in which there will be a link to enter the wp-admin dashboard in a special emergency mode with all plugins disabled, and the theme replaced with the default Twenty-Twentysomething.
The Problems of the New Default WordPress Behavior
The biggest issue with this new feature is that it doesn’t necessarily work as promised at all (“This update will let you safely fix or manage fatal errors without requiring developer time.”). Sure: the ‘magic link’ will disable the offending plugin or theme, but will do nothing to address the root cause for the malfunction.
If the fatal error occurred immediately after a plugin or theme update, the sysadmin will probably put two and two together, and roll back the offending update. But what if this error is not spotted immediately? Or if the error occurs within an obscure branch of code that gets executed infrequently? Or — less likely but definitely not out of the question — the error is caused by a change to the web server configuration like an upgraded PHP version?
Regardless of the root cause, the person responsible for the website will only know there is a problem but not where to look for that problem. In a manner, WordPress is actively trying to hide the error from the admin, even at the expense of disabling what might be core website functionality.
Disabling a plugin or a theme — even worse! — is rarely the preferred solution simply because we tend to install plugins and themes because we need them. A plugin might be there to make a vital change to the standard way WordPress works. If it causes errors, disabling it does not fix anything but simply introduces a different problem, which might be much bigger and costlier.
That is why, if a plugin that is vital to the operation of a website breaks, the site owner needs to fix it immediately, not to remove it. The polite message presented by WordPress actually puts us farther back on our path of finding the root cause of an issue and fixing it. So let’s see how to get past it.
Enter WP_DEBUG mode
WordPress has a powerful mode created for troubleshooting various issues. It instructs WordPress to either log and/or show on screen all warnings and errors which PHP reports. On a development or staging website, this mode is usually kept enabled at all times, so that every warning or error is noticed immediately.
However because these error reports might reveal privileged information, it is a good practice to keep this mode disabled on production websites.
If you maintain a mission critical WordPress website, I assume you always test every update and configuration change on a separate staging website first. But things happen, and if/when some bug breaks through, it is no longer viable to try to reproduce the issue on a staging website. Your number one task should be to restore normal operation to your production website. So let’s break the glass and enter WordPress debug mode.
This involves adding several commands to the wp-config.php file. Most WordPress troubleshooting guides will show you those 3 lines:
// Enable WP_DEBUG
define('WP_DEBUG', true);
// Write errors to a log file located at wp-content/debug.log
define('WP_DEBUG_LOG', true);
// Show errors on screen
define('WP_DEBUG_DISPLAY', true );WP_DEBUG is a global on/off switch; if it is set to ‘false’, it doesn’t matter if either WP_DEBUG_LOG or WP_DEBUG_DISPLAY is set to ‘true’ — errors will not be logged or shown on screen.
However, the hidden failure of the well-meaning ‘Critical Error with Your Site’ error message is that you will still be unable to see any errors because the error handler page is cutting you off from the website. You need to also turn off fatal error handling in order to see the actual error.
// Disable Fatal Error Handle
define('WP_DISABLE_FATAL_ERROR_HANDLER', true );Faster Access to WP_DEBUG Settings
As mentioned above, these 4 commands need to be placed within wp-config.php. However, this means that when I am done fixing the error, I need to come back and edit at least two of them to ‘false’ (WP_DEBUG and WP_DISABLE_FATAL_ERROR_HANDLER).
I have been doing this for way too long and it has become really boring. Also, I no longer find it optimal. So these days, I prefer to do something else: I add all of these settings to a new file called wp-debug.php that looks as shown below (observe the opening tag which allows PHP to recognize the file as code:
<?php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', true );
define('WP_DISABLE_FATAL_ERROR_HANDLER', true );I then open wp-config.php and place the following line at the very beginning (after its own <?php opening tag):
<?php
include (__FILE__ . '/wp-debug.php');The ‘include’ directive instructs PHP to insert the mentioned file in this very place. However, if the file does not exist, php will not signal an error but will simply continue execution from the next line.
When I am done with error diagnostics and fixing, I have two choices to exit the debug mode. I can re-open wp-config.php and comment on the include statement:
<?php
// include 'wp-debug.php';Or, I can instead simply rename wp-debug.php to something like wp-debug.php.disabled .
What Next?
As I said earlier, figuring out the specific reason for the error that triggered the PHP error protection is outside the scope of this article. I have planned other articles that will discuss how to read and interpret PHP error messages; how to anticipate problems due to PHP version changes; how to restore previous versions of plugins and themes from either the command line or via plugin, and so on.
The purpose of this column is to set the groundwork, and to show you how to get rid of a well-meaning but sometimes counter-productive feature.
If you are a customer of WPX, you can simply take advantage of their industry-leading ‘Fixed For You‘ guarantee and let their friendly and qualified support staff take over. You can tell them that you have disabled the PHP Fatal Error Handler, and have enabled WP_DEBUG mode — I am sure that they will appreciate what you have done to help them investigate and fix the issue.
Recap
In this column, I explained how WordPress behaves when there are errors in the programming code. I showed you how to change the default behavior which conceals the cause of the error and puts the whole website in a basic mode, and how to activate the powerful debug mode in order to identify the issue and fix it.
Regardless of whether you will do the fixing on your own, or you will ask for help from your hosting company, this is the very first step to take on the path of solving the issue.
