“There has been a critical error on this website”. The Complete Guide on WordPress Debugging and Error Reporting

Approaching errors methodically can save you hours of frustration and put you in a much better position to find a working solution. At the end of the day, technical problems are not voodoo magic, and they don't get better with time. Every issue has a specific cause - sometimes a single factor, sometimes a combination of problems - that needs to be identified before the right fix can be applied.

The good news is that WordPress, thanks to its popularity, is quite well documented. Chances are the error you’re facing has already been encountered and solved by other users. In most cases, the process comes down to pinpointing the actual error and then researching online for proven solutions. That’s essentially what we do as support professionals: identify, research, and apply the fix. Speaking of "pinpointing the actual error", knowing how to enable all the different features of WordPress debugging and error reporting is the first and perhaps most crucial step towards successfully resolving the problem.

• Enabling the WordPress Error Logging and Reporting
• Enable WP_DEBUG
• Enable WP_DEBUG_LOG
• Enable WP_DEBUG_DISPLAY
• Enable SCRIPT_DEBUG
• Enable SAVEQUERIES
• WordPress Error Reporting Made Easy at ICDSoft
• Examining the Apache Error Log
• Debugging WordPress Queries and PHP Errors Using a Plugin
• Enabling PHP Error Logging
• Using the Browser Console
• Best Practices When Debugging WordPress
• Use a staging instance
• Avoid error messages on live sites
• Clear all possible caching mechanisms
• Conclusion

Enabling the WordPress Error Logging and Reporting

Quite often, our users would come to us and report a problem on their website, but without an actual error message. A certain functionality on their site might not be working as expected, or their entire site could be showing the so-called "white screen of death" (WSoD).

In such cases, our first mission is to find the actual error message. In turn, this helps us identify the WordPress component at fault. Most of the time, it's a particular plugin, but it could also be related to the active theme, or even a WordPress core file, although that's the least likely scenario.

Enable WP_DEBUG

WordPress has a built-in debugging functionality, which checks for PHP code issues in all components, including plugins and themes. To use it, you just need to change the value of the WP_DEBUG PHP constant defined in the wp-config.php file from FALSE to TRUE. Here is a screenshot of a typical WordPress configuration file with the WP_DEBUG constant:

The WP_DEBUG constant should be present by default in your wp-config.php file. If it's not there, you can add it yourself by pasting the following line using the File Manager of your web host or an FTP client such as FileZilla to edit the file:

define( 'WP_DEBUG', TRUE );

You can add the code as a new line anywhere after the opening <?php tag and before the following:

/* That's all, stop editing! Happy publishing. */

Make sure to save the file after adding/modifying the WP_DEBUG constant. Once you've done that, you should go ahead and reproduce the actual problem - whether it's a WSoD or a feature that's not working as expected. This time you should see an actual error message directly on your website, such as:

Enable WP_DEBUG_LOG

The truth is, having error messages displayed on your live website is not a great look for visitors. Instead, you can opt to have the errors saved in a log file and prevent them from being shown publicly. This is done by adding two different constants to your wp-config.php file.

To have the error messages saved in a log file, you would have to add the following line:

define( 'WP_DEBUG_LOG', TRUE );

To keep things organized, it's best to add it right after the WP_DEBUG line quoted above. Activating the WP_DEBUG_LOG setting (make sure to save the wp-config.php file) will cause WordPress to save all errors in a file named debug.log in the /wp-content folder.

Enable WP_DEBUG_DISPLAY

Hiding the actual error messages from the frontend of your WordPress website is done by adding the WP_DEBUG_DISPLAY constant (set to FALSE) in your wp-config.php file:

define( 'WP_DEBUG_DISPLAY', FALSE );

The idea is to use it in combination with WP_DEBUG and WP_DEBUG_LOG set to TRUE. Otherwise, no errors will be shown or logged, and you won't get any details at all. Having WP_DEBUG and WP_DEBUG_LOG set to TRUE along with WP_DEBUG_DISPLAY set to FALSE will hide the actual error messages from your website visitors, while logging them in the debug.log file inside the /wp-content folder. This is in fact the recommended (best practice) configuration for live websites.

Enable SCRIPT_DEBUG

In order to reduce load times, WordPress loads minified versions of its core JavaScript and CSS files. However, these files are compressed and much harder to debug. Enabling SCRIPT_DEBUG in the configuration file makes WordPress use the non-minified (development) versions of those files. This is useful if you are debugging JavaScript or CSS problems, and you want more detailed error messages in your browser console (which we will also cover in this tutorial).

To enable SCRIPT_DEBUG, you should add the following line in your wp-config.php:

define( 'SCRIPT_DEBUG', TRUE );

This will cause WordPress to load the development versions of its own core JavaScript and CSS files, as well as those of your active plugins and theme - with one small caveat: the plugin and theme developers must have actually provided such versions.

Here is an example of a non-minified, "development" version of a JavaScript file:

/wp-includes/js/jquery/jquery.js

Here is the corresponding minified version of that file:

/wp-includes/js/jquery/jquery.min.js

If you don't have the SCRIPT_DEBUG constant explicitly set in your configuration file, WordPress will operate with the script debug mode turned off (and load the minified versions of all JS and CSS files).

Again, it's important to outline the fact that WordPress plugin and theme developers are not required to provide both minified and development versions of their JS and CSS files. There are a lot of plugins that only provide the minified version. Typically, however, good-quality plugins and themes include both following the same naming convention:

• file.js and file.min.js

• style.css and style.min.css

Bottom line is that the SCRIPT_DEBUG mode could be really useful if you are debugging a WordPress core problem, or if you are developing a plugin or theme. Enabling it will allow you to see the actual source code of all JS/CSS files (that support it), instead of minified, compressed files that are nearly impossible to read.

Enable SAVEQUERIES

Another really useful feature part of the integrated WordPress debugging is SAVEQUERIES. Setting the SAVEQUERIES constant to TRUE in your WordPress configuration file makes WordPress save all database queries executed during page load to an array along with stats showing just how long it took for each query to complete.

This is really useful when you are trying to debug slow MySQL queries hampering the loading times of your website. The log file will show the execution time of each query as well as the script that triggered it. Based on the script's path and name, you can easily find if a particular plugin is seriously slowing down your site.

What has to be noted about the SAVEQUERIES option is that capturing the actual output is not as easy as just setting the constant to TRUE in your wp-config.php file. The thing is that the actual data (MySQL query, script that triggered it, and the execution time) is stored in a global WordPress database access object named $wpdb. Thus, you would have to add a few lines of code that will dump its output in a log file under your account. Since we want to save all queries executed during page load, it's best to add this code in the active theme's footer to ensure all queries have already run. Let's cover in detail each step, so you can take full advantage of the most useful WordPress database debugging tool.

As you can probably guess, step one is adding a line in your wp-config.php file that will set the SAVEQUERIES constant to TRUE. You should add it anywhere before the line that says ‘That’s all, stop editing!’, preferably next to the other WordPress debugging constants we just covered:

define( 'SAVEQUERIES', TRUE );

Step two is to add the following code snippet in the footer.php file of your active theme. If you are not sure which your active theme is, you can go to your WordPress dashboard and look under the Appearance menu > Themes. There, look at the one with the "Active" sign. The other option is to obtain the name of the theme using the following WP-CLI command:

wp theme list

This command will list all themes currently installed on your WordPress site. You should look for the one with the "active" label. That's your active theme.

Now that you know the (active) theme your WordPress installation is using, it's time to add a code snippet in its footer.php file in order to extract the data from the $wpdb object. The files of your active WordPress theme would be in the /wp-content/themes folder. You can navigate to it using your hosting account's File Manager. In our example, the files of our active Astra theme would be in the /wp-content/themes/astra folder. There, you should open the footer.php file:

Open the footer.php file with your File Manager and place the following code in it:

<?php
if ( defined('SAVEQUERIES') && SAVEQUERIES ) {
    global $wpdb;

    $log_file = WP_CONTENT_DIR . '/query-log.txt';
    $output = '';

    foreach ( $wpdb->queries as $query ) {
        $output .= sprintf(
            "Query: %s\nTime: %f sec\nCaller: %s\n\n",
            $query[0],
            $query[1],
            $query[2]
        );
    }

    file_put_contents( $log_file, $output, FILE_APPEND );
}
?>

You should add it at the bottom of the file, before the closing </body></html> tags.

This will save all queries executed on the page you are accessing to a file named query-log.txt in the/wp-content folder. The output will include all MySQL queries triggered on that page, along with their corresponding execution time and caller function/file.

So once you add this code to the footer.php of your active WordPress theme, you should open/reload the page you want to examine and then check the /wp-content/query-log.txt file. Here is an example of the output you will get:

WordPress Error Reporting Made Easy at ICDSoft

If you are hosted at ICDSoft, you won't have to "get your hands dirty" and modify the code of the WordPress configuration file manually. The WordPress Manager in the Control Panel allows you to easily manage the different WordPress debugging settings with just a few clicks.

To make use of this functionality, go to the WordPress Manager and press the Manage button next to the installation that you want to debug.

On the next screen, scroll down, and you will see the Debugging section. Note that enabling the WP_DEBUG option will automatically turn on WP_DEBUG_DISPLAY, so the error messages will be visible directly on your website. If you are working on a live website, it's best to turn off the WP_DEBUG_DISPLAY setting and switch on the WP_DEBUG_LOG instead. As you've now learned, this will cause WordPress to save the error messages in a debug.log file under the /wp-content folder. Of course, if you are working on a staging instance (as you should be, and we will get to that too), then it's perfectly fine to leave the default combination of WP_DEBUG + WP_DEBUG_DISPLAY turned on.

As you can see, the WordPress Manager in the ICDSoft Control Panel allows you to easily switch on and off all the different debugging options we just covered - WP_DEBUG, WP_DEBUG_LOG, WP_DEBUG_DISPLAY, SCRIPT_DEBUG, SAVEQUERIES.

Examining the Apache Error Log

There are cases where the native WordPress debugging won't help. As you probably know, WordPress comes with a default .htaccess file that instructs the Apache web server how to handle the requests for your website. A lot of WordPress plugins, particularly those related to performance (caching, optimization) and security (e.g. Wordfence) add various directives to the .htaccess file. Users might add their own custom rewrite rules. Eventually, the .htaccess file could get quite large with hundreds and sometimes thousands of lines in it, making it difficult to work with.

Quite often, we will have cases where a user might have accidentally introduced a syntax error in the .htaccess file, as just the addition of a single symbol at the wrong place would break a WordPress website and trigger an error. It's also possible that a plugin update or setting change did not fully complete, resulting in incomplete (incorrect) directives and rewrite rules. Syntax errors in the WordPress .htaccess file lead to a "500 SERVER ERROR" message displayed on your website. There won't be any details in the WordPress error logs, because the application won't even load.

To troubleshoot such errors, you would have to look elsewhere. And since we mentioned that the .htaccess file is similar to a configuration file for the Apache web server, one must look at the Apache error logs for details. Depending on your web host, you might not have direct access to the Apache error log, but users at ICDSoft have a convenient tool at their disposal.

The Logs section in the hosting Control Panel allows you to view the Apache logs in almost real time. The Live HTTP Logs subsection is where you can find both the access and error logs of the Apache web server. The live logs will be enabled within one minute after you open the Live HTTP logs subsection, and they will be disabled six hours after you close the subsection. Thus, you should expect a delay of up to several minutes. So, if you encounter a "500 SERVER ERROR" on your website, open the Live HTTP Logs subsection and wait for a couple of minutes for the actual error to appear.

In this particular case, the error we have is "/home/example/www/www/.htaccess: Invalid command '', perhaps misspelled or defined by a module not included in the server configuration". This tells us that we have an invalid command in our .htaccess file, so we would have to find it and correct it.

Spoiler alert 🚨: I had intentionally added a "<" tag at the end of the file in order to trigger the error. 

Debugging WordPress Queries and PHP Errors Using a Plugin

There are some WordPress plugins that can be quite useful in debugging various errors related to the platform. For example, WP Control can help with issues with scheduled posts as it allows you to view and manage (edit, delete, pause, resume, run) all cron events, and when they are next due.

But perhaps the most popular WordPress debugging plugin is Query Monitor. Once you install and activate the plugin, you just need to open a given page on your WordPress website (while logged in as administrator), and you will see a detailed list of all the scripts that were loaded, all the CSS styles, HTTP API calls, hooks and actions, and perhaps most importantly - the database queries that were triggered by that specific page. This could be really useful in investigating problems with slow page loads or high MySQL usage. Note that in order to use the database queries feature, you would have to enable the SAVEQUERIES constant, as we just covered. In a nutshell, this plugin will simply output the data we covered in the Enable SAVEQUERIES chapter, but in a more convenient manner, as you won't have to add a script to your theme's footer file.

Enabling PHP Error Logging

One might wonder why we would need to enable or even consider the PHP error log when we've already covered all the features of the native WordPress debugging. Indeed, WordPress comes with an extensive logging functionality, but there are still cases where you could make use of PHP's error reporting as well.

For example, there are more complex websites that combine WordPress with custom PHP scripts, and the WordPress debugging output won't contain any details on those scripts. There are also cases where another PHP script loads before WordPress does. Wordfence is a prime example of this behavior. It's arguably the most popular security plugin, and its Extended Protection Mode uses the PHP.ini setting called auto_prepend_file in order to ensure it runs before any potentially vulnerable code runs. It does that by adding the following line to a .user.ini file in the folder where WordPress is installed:

auto_prepend_file = '/home/example/www/www/wordfence-waf.php'

And that's why it can be quite useful to also have PHP error reporting turned on even if you've already enabled the WordPress debugging. Managing your PHP settings can be quite specific depending on your web host, but in general, you should be able to do it by adding the following lines to a php.ini or a .user.ini file in the folder where your WordPress installation resides (same folder as wp-config.php):

error_reporting = E_ALL
log_errors = On
display_errors = Off
error_log = /home/username/logs/php-error.log

You should replace username with your actual hosting account username.

Here is a quick explanation of each setting:

• error_reporting = E_ALL - Instructs PHP to log everything.
• log_errors = On - Logs errors to a file.
• display_errors = Off - Don’t show errors to visitors (important for live sites).
• error_log = … - The path to your log file.

At ICDSoft, you can easily enable PHP error logging via the PHP Settings section in the Control Panel or via the WordPress Manager > Performance > Used PHP Version > Manage.

Once you are at the PHP Settings page, if you don't have a PHP configuration file (php.ini), the system will give you the option to Create one. You will then see all the different directives under the Advanced configuration settings section on the right side. There, you can set the error_reporting to E_ALL, and press the Show additional directives button to also manage the display_errors, error_log, and log_errors directives.

Using the Browser Console

The browser console is one of the best tools for debugging frontend problems with WordPress websites, particularly issues with JavaScript, AJAX, or CSS. It will allow you to see error messages that would otherwise go unnoticed. For example, browsers no longer show an X sign if an image is missing from the page, they simply render it without it. Only by looking at the browser console would you be able to see if certain images or resources have failed to load.

If you are on Windows or Linux, you would be able to open the browser console in most browsers (Chrome, Edge, Firefox) by pressing Ctrl + Shift + J. For macOS with Safari, you should use Cmd + Option + J.

One of the most common WordPress problems we handle as tech support personnel at ICDSoft is concerning missing sliders, images, broken layout, and "not secure" warnings at the browser address bar. Quite often, all these issues are attributed to resources being loaded over plain HTTP connection instead of HTTPS. To get to the bottom of an issue, our support members use the browser console, where they would see entries such as:

Mixed Content: The page at 'https://.../' was loaded over HTTPS, but requested an insecure image 'http://...'. This request has been blocked; the content must be served over HTTPS

That's why reading the browser console can be extremely helpful in debugging a wide range of WordPress problems.

Best Practices When Debugging WordPress

We have covered a lot of ground in the field of WordPress debugging. Now that you are armed with all the necessary tools for the job, the final step is to review (and implement) the best practices to follow before diving deep into error logging and reporting.

Use a staging instance

The number one rule to follow whenеver you have to fiddle and tweak around with WordPress is to set up a staging instance. This will allow you to experiment safely without doing further damage and without exposing any unnecessary error messages to your website visitors.

Manually creating a WordPress staging instance can be a bit complex and time-consuming task. We have already covered the process extensively in our blog.

How to Set Up a WordPress STAGING Site & COPY/MOVE WordPress – The ULTIMATE GUIDE!

Once you have the staging instance up and running, you can apply all the techniques covered in this article safely to it, knowing that your debugging efforts won't interfere with the operation of the live site in any way.

Avoid error messages on live sites

If you do have to work on a live website, and you can't set up a staging instance for some reason, then it's really important to not display any errors message and log them to a file instead. We covered this method in the part for enabling WP_DEBUG_LOG.

Clear all possible caching mechanisms

WordPress caching comes in a lot of different forms, and quite often it gets in the way of debugging and trying to resolve problems with the platform. You might have enabled error reporting, but no messages are showing up only because you are accessing a cached copy of the site. That's why it's really important to identify and then clear/purge or even temporarily disable all available caching methods before you even get started.

The subject of WordPress caching is quite vast, and it's probably worth dedicating an entire blog post solely to it. For example, the website could be using one of the popular caching plugins, such as Litespeed, WP Rocket, or W3 Total Cache. Or the actual web host could be providing its own server-side caching tool, such as the one we have at ICDSoft. And thirdly, the caching could be happening on a CDN, such as Cloudflare or Gcore, or any other CDN solution that could be integrated into the web hosting platform.

Bottom line is that you should check if and what types of caching the WordPress installation is using, and then use the clear/purge option there. This will ensure that you get all the latest data, and all the changes you make will take effect immediately.

Conclusion

WordPress comes with an extensive set of options for error logging and reporting. When you combine these with additional sources of information - such as the web server (Apache) error logs, PHP error logs, and the browser console - you have a powerful toolkit at your disposal to see what's really happening under the hood. After all, identifying the actual problem is the first, and perhaps most important step towards resolving it.