Fix PHP White Screen of Death - How to find the cause

Wed, 2017-11-22 01:35

PHP has certain configuration options that can hide any errors in the code it runs, and this sometimes results in a complete blank browser page without any clues what caused that error. It goes without saying that this is very frustrating when you are don't recall what you changed recently or when there is a team of developers butchering the same code without testing them.

Here are some quick steps if you run into a WSOD. Many of you might know this already, but I'm putting the snippets below for copy pasta pleasure of yours and mine.

Make sure it is indeed an error page

It is possible that the PHP did not throw any error, but simply returned an empty response. The easiest way to see it is checking the response code of the request. Open up the developer tools in your browser (F12 in most browsers) and check the response code of the page. If it says 200, that means the PHP code did run well. There can be PHP errors, but none of them have caused the server to send the empty response. Seeing a 500 error, then you know things have gone south.

Firefox developer tools showing 500 error

Enable error display

It is possible that your PHP configuration has turned error display off. You can easily enable error reporting for all incidents, and enable error display.

In your PHP file, preferably in the entry point of the application, copy-pasta the following snippet.

ini_set('display_startup_errors', true);
ini_set('display_errors', true);

All these INI values are run-time configurable, and will override any settings you might have in your php.ini file.

Reload the page and see if you can see errors.

If you are still seeing errors, it is possible that your code is turning the error display settings off again somewhere. Instead of finding where the application turns off error report, we take the red pill and force PHP to display errors and a trace.


For this, we use the awesome Xdebug PHP extension. If you are using an Ubuntu/Debian system with ondrej/php PPA to source PHP, you can enable Xdebug by simply running sudo apt install php7.1-xdebug. For Windows and other systems, see this.

After enabling Xdebug, set the following settings in the php.ini file under [xdebug] section.

xdebug.default_enable = 1
xdebug.force_display_errors = 1
xdebug.scream = 1
xdebug.force_error_reporting = E_ALL

You will need to reload Apache/php-fpm for the settings to kick in. After that, reload the page and you will see the full error display. It will also SCREAM any errors that you might have silenced with the @ operator, like @do_something_stupid().

Firefox developer tools showing 500 error

Now that you can see the exact error messages, the rest is up to you to deal with ?.