Debugging the Dreaded White Screen of Death

It’s called ‘The White Screen of Death’ for a reason. If you are here, you probably know why.

This is normally caused by PHP hitting an error and stopping, as by default there's no PHP error reporting turned on for the Apache PHP module, so you are left with a blank white screen. The following instructions apply to a development environment only  - NOT A PRODUCTION ONE!

Replicating the error

After a fresh installation of Apache and the Apache php module, if we view this code in a web browser on localhost

<?php
// generate an error on purpose
include 'non-existent-file.php';
?>

we get the white screen of death.

However, if we run the same code from the CLI version of php we do get some useful output:

$ php -f missing-file.php 
PHP Warning:  include(non-existent-file.php): failed to open stream:
No such file or directory in /var/www/html/missing-file.php on line 4
PHP Warning:  include(): Failed opening 'non-existent-file.php' for inclusion 
(include_path='.:/usr/share/php') in /var/www/html/missing-file.php on line 4

Adding error message reporting to php.ini file

We need to tell PHP to output some meaningful error messages, by adding the following directives to the php.ini file .

This is for development purposes only - not a production server!

The default values are commented out 

; error_reporting = E_ALL & ~E_DEPRECATED & ~E_STRICT
error_reporting = E_ALL

; display_errors = Off
display_errors = On

; display_startup_errors = Off
display_startup_errors = On

Depending on your platform, you might be able to leave error_log at its default value. This example is set to log to Apache's error.log file on Linux.

; Log errors to specified file. PHP's default behaviour is to leave this value empty.
; http://php.net/error-log
; Example:
;error_log = php_errors.log
; Log errors to syslog (Event Log on Windows).
;error_log = syslog
error_log = "/var/log/apache2/error.log"

Restarting Apache

Having added those error reporting directives to your php.ini file, you will need to restart Apache to make the php module read those configuration changes.

On Linux this can be done as an administrator with:

# systemctl restart apache2 --no-pager

Once Apache has been restarted and you reload the page with the missing include file, you should see PHP error messages instead of a blank white screen:

And checking Apache's default error.log file, you should also see the same error message there:

[Thu Aug 18 15:26:35.585205 2022] [php7:warn] [pid 141054] [client 127.0.0.1:55978] PHP Warning:  include(non-existent-file.php): failed to open stream:
No such file or directory in /var/www/html/missing-file.php on line 4,
referer: <a href="http://localhost/">http://localhost/</a> <br>[Thu Aug 18 15:26:35.585261 2022] [php7:warn] [pid 141054] [client 127.0.0.1:55978] PHP Warning:  include(): Failed opening 'non-existent-file.php' for inclusion
(include_path='.:/usr/share/php') in /var/www/html/missing-file.php on line 4,
referer: <a href="http://localhost/">http://localhost/</a>

If that still does not help

Did you recently install a plugin? Take a look at this flow chart to see if you can resolve the issue.

If the White Screen of Death was not caused by a plugin, below we provide some basic steps you can follow to begin debugging it:

  1. SFTP to your document root
  2. Change into the WordPress directory.
  3. View or download the php-errors.log file.
  4. Take a look at the last few lines of the error log to determine the cause of the white screen.

You might see a very specific PHP error which will provide a line number in the file that’s causing the problem. At this point you can:

  1. Download the file that’s causing the problem.
  2. Go to the line that was listed in the error log.
  3. Fix the issue.
  4. Upload the file back to the server.
  5. Test your website.

If the white screen does not go away then repeat all of the steps above. Sometimes there could be more than one error.