How do I catch a PHP fatal (`E_ERROR`) error?

How do I catch a PHP fatal (`E_ERROR`) error?

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

Why set_error_handler() Cannot Catch Fatal Errors in PHP

You've likely encountered the standard pattern for handling non-fatal errors in PHP: calling set_error_handler() and defining a callback that logs or formats the message before passing it along. This works perfectly for warnings (E_WARNING) and notices (E_NOTICE). However, when you attempt to intercept a fatal error like E_ERROR—often triggered by calling a non-existent function—you will find that the handler simply never fires.

This isn't a configuration issue or a version-specific bug; it is a fundamental design decision in the PHP runtime. Fatal errors are distinct because they represent an unrecoverable state for the current execution context. When PHP encounters an error marked as fatal, it immediately stops parsing and executing the script. The control flow does not return to your set_error_handler() callback because the engine treats these events as termination signals rather than standard exceptions or warnings that can be caught and processed.

In the specific scenario you described with PHP 5.2.3, trying to route all errors, including those for missing functions, into a single logging mechanism via mail(), hits this hard limit. The function call fails so abruptly that the script halts before any custom handler registered via set_error_handler() has a chance to execute.

The Role of register_shutdown_function

If you need to perform cleanup or logging after an uncaught fatal error occurs, the mechanism provided by PHP is register_shutdown_function(). Unlike set_error_handler(), which intercepts errors during normal execution flow, register_shutdown_function() registers a callback to be executed when the script terminates. This includes termination via a fatal error (E_ERROR), a die() call, or reaching the end of the script normally.

Here is how you can implement a fallback handler specifically for fatal errors:

function shutdownHandler() {
    $error = error_get_last();
    
    if ($error !== null && (
        $error['type'] === E_ERROR || 
        $error['type'] === E_CORE_ERROR || 
        $error['type'] === E_COMPILE_ERROR
    )) {
        // Log the fatal error or send email here
        // Example: mail_log($error['message']);
        
        // Optionally, prevent further shutdown processing to avoid noise
        exit;
    }
}

register_shutdown_function('shutdownHandler');

This approach captures the last known error state in the $error array. By checking the type property against E_ERROR, E_CORE_ERROR, or E_COMPILE_ERROR, you can isolate fatal-level issues from other termination causes. This is often the most robust way to ensure that critical failures, such as calling a non-existent function, trigger your logging logic before the application crashes completely.

Trade-offs and Limitations

Using register_shutdown_function introduces specific trade-offs that every developer must consider. The primary limitation is timing: since these functions run only after the script has already crashed, you cannot use this method to prevent the error from happening or to provide a graceful degradation within the current request logic. You are strictly reacting to failure.

Furthermore, there is a risk of outputting unexpected messages. If your shutdown handler generates HTML or text output without proper context, it may confuse users who have already seen an unhandled exception message in their browser's error log. It is often best practice to keep the output within the handler minimal or silent, relying on server-side logging (like Apache or Nginx access/error logs) for investigation.

Another consideration involves the order of operations. If you rely on mail() within the shutdown function, ensure that your mail configuration is robust enough to handle a crashed script environment. Sometimes, if the fatal error corrupted internal state, attempting to send an email might itself fail silently or throw additional errors that clutter your logs.

Contextual Solutions with Modern Frameworks

If you are maintaining legacy applications on older PHP versions like 5.2.3, you may be bound by these constraints due to version limitations. However, in modern development environments, frameworks like Laravel abstract much of this complexity away. They often integrate custom error handlers and shutdown logic directly into the framework's kernel, ensuring that fatal errors are logged consistently without requiring manual intervention for every single request.

For projects built on such platforms, you might look at resources like https://laravelcompany.com to understand how modern frameworks handle error reporting out of the box, potentially offering a more seamless experience where fatal errors are caught and reported via structured logging systems rather than raw PHP shutdown functions. This shifts the burden from writing manual shutdown handlers to configuring framework-level error reporting strategies, which are generally safer and easier to maintain at scale.

Ultimately, understanding that set_error_handler() has no reach into fatal territory is crucial for designing resilient applications. By leveraging register_shutdown_function and being mindful of its reactive nature, you can ensure that even the most critical failures do not go unnoticed by your monitoring systems.

Our network