Actions and filters for WordPress error handling.

Actions

wp_error_added

Fires when an error is added to a WP_Error object.

do_action( 'wp_error_added', string|int $code, string $message, mixed $data, WP_Error $wp_error )

Since: 5.6.0
Source: WP_Error::add()

Example:

add_action( 'wp_error_added', function( $code, $message, $data, $wp_error ) {
    // Log all errors
    error_log( sprintf( 'WP_Error: [%s] %s', $code, $message ) );
    
    // Track specific error codes
    if ( $code === 'rest_forbidden' ) {
        do_action( 'my_access_denied_tracking', $message, $data );
    }
}, 10, 4 );

is_wp_error_instance

Fires when is_wp_error() detects a WP_Error instance.

do_action( 'is_wp_error_instance', WP_Error $thing )

Since: 5.6.0
Source: is_wp_error()

Example:

add_action( 'is_wp_error_instance', function( $error ) {
    // Debug logging for development
    if ( WP_DEBUG ) {
        error_log( 'WP_Error encountered: ' . $error->get_error_message() );
    }
} );

Note: This fires every time is_wp_error() returns true, which can be frequent. Use sparingly.

Filters

wp_die_handler

Filters the callback for killing WordPress execution (default/HTML requests).

apply_filters( 'wp_die_handler', callable $callback )

Since: 3.0.0
Source: wp_die()

Example:

add_filter( 'wp_die_handler', function( $handler ) {
    return function( $message, $title, $args ) use ( $handler ) {
        // Custom logging
        error_log( "wp_die: $message" );
        
        // Custom template for frontend
        if ( ! is_admin() ) {
            include get_template_directory() . '/error.php';
            exit;
        }
        
        // Default for admin
        call_user_func( $handler, $message, $title, $args );
    };
} );

wp_die_ajax_handler

Filters the callback for killing WordPress execution for Ajax requests.

apply_filters( 'wp_die_ajax_handler', callable $callback )

Since: 3.4.0
Source: wp_die()

wp_die_json_handler

Filters the callback for killing WordPress execution for JSON requests.

apply_filters( 'wp_die_json_handler', callable $callback )

Since: 5.1.0
Source: wp_die()

wp_die_jsonp_handler

Filters the callback for killing WordPress execution for JSONP REST requests.

apply_filters( 'wp_die_jsonp_handler', callable $callback )

Since: 5.2.0
Source: wp_die()

wp_die_xmlrpc_handler

Filters the callback for killing WordPress execution for XML-RPC requests.

apply_filters( 'wp_die_xmlrpc_handler', callable $callback )

Since: 3.4.0
Source: wp_die()

wp_die_xml_handler

Filters the callback for killing WordPress execution for XML requests.

apply_filters( 'wp_die_xml_handler', callable $callback )

Since: 5.2.0
Source: wp_die()

wp_should_handle_php_error

Filters whether a PHP error should be handled by the fatal error handler.

apply_filters( 'wp_should_handle_php_error', bool $should_handle, array $error )

Since: 5.2.0
Source: WP_Fatal_Error_Handler::should_handle_error()

Note: This filter only fires for errors NOT already handled by default (E_ERROR, E_PARSE, etc.). It allows adding more error types.

Example:

add_filter( 'wp_should_handle_php_error', function( $should_handle, $error ) {
    // Also handle E_WARNING in production
    if ( $error['type'] === E_WARNING && ! WP_DEBUG ) {
        return true;
    }
    return $should_handle;
}, 10, 2 );

wp_fatal_error_handler_enabled

Filters whether the fatal error handler is enabled.

apply_filters( 'wp_fatal_error_handler_enabled', bool $enabled )

Since: 5.2.0
Source: wp_is_fatal_error_handler_enabled()

Important: This filter runs before plugins load. Must be defined in wp-config.php:

$GLOBALS['wp_filter'] = array(
    'wp_fatal_error_handler_enabled' => array(
        10 => array(
            array(
                'accepted_args' => 0,
                'function'      => function() {
                    return false; // Disable handler
                },
            ),
        ),
    ),
);

wp_php_error_message

Filters the message displayed by the default PHP error template.

apply_filters( 'wp_php_error_message', string $message, array $error )

Since: 5.2.0
Source: WP_Fatal_Error_Handler::display_default_error_template()

Example:

add_filter( 'wp_php_error_message', function( $message, $error ) {
    // Add contact info
    $message .= '<p>Contact support: [email protected]</p>';
    
    // Add error details in debug mode
    if ( WP_DEBUG_DISPLAY ) {
        $message .= sprintf(
            '<pre>%s in %s on line %d</pre>',
            esc_html( $error['message'] ),
            esc_html( $error['file'] ),
            $error['line']
        );
    }
    
    return $message;
}, 10, 2 );

wp_php_error_args

Filters the arguments passed to wp_die() for the default PHP error template.

apply_filters( 'wp_php_error_args', array $args, array $error )

Since: 5.2.0
Source: WP_Fatal_Error_Handler::display_default_error_template()

Default args:

array(
    'response' => 500,
    'exit'     => false,
)

Example:

add_filter( 'wp_php_error_args', function( $args, $error ) {
    // Add a link to status page
    $args['link_url']  = 'https://status.example.com';
    $args['link_text'] = 'Check system status';
    
    return $args;
}, 10, 2 );

Hook Reference Table

Testing Hooks

For unit tests, use filters to capture wp_die() calls:

// In test setup
add_filter( 'wp_die_handler', function() {
    return function( $message, $title, $args ) {
        throw new WPDieException( $message );
    };
} );

// In test
$this->expectException( WPDieException::class );
wp_die( 'Test error' );