How to disable the fatal error (WSOD) protection?

by

The fatal error handling was introduced in WordPress 5.1 and 5.2.

It’s sometimes referred to as the White Screen Of Death (WSOD) protection.

When working on dev/local installs, we sometimes want to be able to break the sites as needed, and e.g. avoid the email recovery process for the site when working within a protected endpoint (see is_protected_endpoint()):

The site is experiencing technical difficulties. Please check your
site admin email inbox for instructions.

How can we disable the fatal error handling?

1

We can modify the bool output of the wp_is_fatal_error_handler_enabled() function in two ways:

Constant

Set the WP_DISABLE_FATAL_ERROR_HANDLER constant to true within the wp-config.php file:

/**
 * Disable the fatal error handler.
 */
const WP_DISABLE_FATAL_ERROR_HANDLER = true;

or

define( 'WP_DISABLE_FATAL_ERROR_HANDLER', true );

Filter

Use wp_fatal_error_handler_enabled bool filter:

/**
 * Disable the fatal error handler.
 */
add_filter( 'wp_fatal_error_handler_enabled', '__return_false' );

Notes

See ticket #44458

The wp_fatal_error_handler_enabled filter will override the value of the WP_DISABLE_FATAL_ERROR_HANDLER constant.

Also watch out for a possible bool confusion with the constant disabling but the filter enabling.

In my testing the filter approach, as a must-use plugin, is not working as expected, so I’m using the constant instead. Hopefully I can look into this further.

One can also add a custom drop-in file fatal-error-handler.php into the wp-content directory (src), to override the WP_Fatal_Error_Handler class as needed. We must use a different class name and it must define the handle() method as the registered shutdown function.

A simple example to disable it would be to override the default error handler class with a custom one that does nothing:

<?php
class WPSE_Fatal_Error_Handler {
    public function handle() {}
}
return new WPSE_Fatal_Error_Handler;

Anonymous class in PHP 7+ seems to work as well:

<?php
return new Class(){
    public function handle() {}
};

It could also extend the default WP_Fatal_Error_Handler class if needed.

Then there’s the WP_SANDBOX_SCRAPING constant. See #46045

Setting the WP_DEBUG as true will not disable the WSOD protection. This is by design. See #46825

Leave a Comment