How can I debug a white screen?

What is a White Screen?

# Top

A “white screen” is the symptom of a 500 error. 500 errors are the result of PHP code execution errors or failures and may be caused by plugin and theme conflicts, errors or bugs in code, and more.

If you’re seeing a 500 Error on your site that means something is wrong but in order for us to help we need to know what the error is to help resolve it.

By default, WordPress suppresses all errors to prevent sensitive information from being leaked. But, without that information we’re unable to determine the source of the problem and therefore we’re pretty helpless to resolve the issue.

If you’re seeing a white screen you can temporarily enable WP_DEBUG which will allow us to see the error message (instead of just a blank white screen) and then we can set to work resolving the problem.

Debugging Modes

# Top

WP_DEBUG can be enabled by editing your site’s wp-config.php file using an FTP client or a file manager. This cannot be edited via the WordPress admin panel.

You can easily crash your website by adding invalid PHP code to your site. Be careful when editing a live site’s PHP files!

It’s likely that some or all of the example code already exists in your wp-config.php file. If it’s already there you’ll want to remove or modify the existing define() statements instead of simply pasting the examples. Multiple definitions for the same constant will result in NEW PHP errors so pay attention when adding this code!

There’s three debugging levels that you can enable:

  • WP_DEBUG enables debugging
    • Errors will be visible depending on your server’s error reporting settings
    • Must be enabled for the following two methods to function.
  • WP_DEBUG_DISPLAY shows errors on screen.
    • This is the fastest and easiest way to find an error causing a white screen.
    • This will display error and warning messages to any visitor to your website.
    • If you’re seeing 500 in AJAX, displaying the error messages won’t help.
  • WP_DEBUG_LOG records error messages to a log file located on your server at wp-content/debug.log.
    • This will prevent visitors from seeing any error messages on your site.
    • If you’re seeing 500 errors in AJAX calls this is the best way to find the related error message.

It’s possible to enable both WP_DEBUG_LOG and WP_DEBUG_DISPLAY at the same time!

Enable Error Reporting Only

# Top

To enable visual onscreen error reporting only (no logging) add the following to your wp-config.php before /* That's all, stop editing! Happy blogging. */

Enable Error Logging Only

# Top

To enable error logging to the wp-content/debug.log file only (no visual error reporting) add the following to your wp-config.php before /* That's all, stop editing! Happy blogging. */

Enable Error Logging and Reporting

# Top

To enable both error reporting and error logging add the following to your wp-config.php before /* That's all, stop editing! Happy blogging. */

Disable Error Display

# Top

When you’re done troubleshooting it is important to turn, at least, WP_DEBUG_DISPLAY off. You do not want all the notices, warnings, or errors showing up on the front of your site!

If you head back into your wp-config.php file you’ll want to turn the true back to false for WP_DEBUG or at least WP_DEBUG_DISPLAY if you’d like to continue recording your error logs on the backend:

define( 'WP_DEBUG_DISPLAY', false );

Last Updated on
Was this article helpful?