alleyinteractive/wp-fatal-handler

A better fatal error handler for WordPress.

v0.1.2 2025-07-02 15:24 UTC

GPL-2.0-or-later

• Sean Fisher

• alleyinteractive
• wp-fatal-handler

README

Contributors: alleyinteractive

Tags: alleyinteractive, wp-fatal-handler

Stable tag: 0.1.2

Requires at least: 6.3

Tested up to: 6.7

Requires PHP: 8.2

License: GPL v2 or later

A better fatal error handler for WordPress powered by Whoops.

By default, WordPress' error handling provides limited information when dealing with fatal errors.

This plugin replaces the default WordPress fatal error handler with a Whoops error handler, which provides a much more useful error page with stack traces, code snippets, and more. It also provides a JSON response for API requests. The Whoops handler will only be applied to fatal errors where WP_DEBUG is set to `true.

Installation

You can install the package via Composer:

composer require alleyinteractive/wp-fatal-handler

Usage

Activate the plugin in WordPress and it will automatically register the Whoops error handler for fatal errors. It is recommended to load this plugin as early as possible (perhaps in mu-plugins), so that it can catch all fatal errors that occur during the WordPress bootstrap process.

Configuration

By default the plugin will register the Whoops error handler and only handle fatal errors (where core usually displays There has been a critical error on this website. ).

To disable the registration of the error handler, you can use the wp_fatal_handler_register filter:

add_filter( 'wp_fatal_handler_register', '__return_false' );

Note: this filter should be applied before the plugin is loaded.

Conflict with Query Monitor

By default Query Monitor will handle fatal errors which will prevent this plugin from displaying its error page. To allow this plugin to handle fatal errors, you can disable Query Monitor's error handling by using the following code:

define( 'QM_DISABLE_ERROR_HANDLER', true );

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

This project is actively maintained by Alley Interactive. Like what you see? Come work with us.

• Sean Fisher
• All Contributors

License

The GNU General Public License (GPL) license. Please see License File for more information.