PHP error guide

Uncaught RuntimeException: meaning and fix

fatal exception Affects: PHP 7.4–8.4 Last verified:

Error summary

Catch the exception only where the application can recover or translate it; otherwise add a top-level logger and preserve the original stack trace.

What it means

Catch the exception only where the application can recover or translate it; otherwise add a top-level logger and preserve the original stack trace.

What the error means

A RuntimeException escaped every matching catch block and reached PHP’s global exception boundary, so execution of the request or command stopped.

Why PHP produces it

The throwing operation reported a runtime failure, but no caller handled RuntimeException or a parent Throwable type before control reached the entry point.

PHP version notes

The behavior described for Uncaught RuntimeException applies to PHP 7.4–8.4 unless a narrower version is stated; exact wording can vary by SAPI and patch release.

Most common causes

  • The exception is thrown outside the try block intended to handle it.
  • A catch block targets an unrelated subtype.
  • A framework or CLI entry point has no final exception-to-response logger.

Minimal examples

BAD — reproduces the problem

php 
try { $orders->save($order); } catch (Throwable $e) {}

FIXED — safer pattern

php 
try { $orders->save($order); } catch (RuntimeException $e) { $logger->error("Save failed", ["exception"=>$e]); throw $e; }

Step-by-step diagnosis

  1. Read the first application frame and the complete previous-exception chain.
  2. Trace callers from the throw site to find the intended recovery boundary.
  3. Confirm logs retain the exception class, message, code, and stack without exposing them to users.

Fixes

Handle at a meaningful boundary

Catch the specific exception where a fallback or response can be produced, and log before translating it.

php 
try {
    $orders->save($order);
} catch (RuntimeException $e) {
    $logger->error("Order save failed", ["exception" => $e]);
    throw new ServiceUnavailableException(previous: $e);
}

Common mistakes when fixing it

  • Catching Throwable everywhere and silently continuing with invalid state.
  • Displaying the production stack trace in the HTTP response.
  • Discarding the previous exception while translating layers.

How to prevent it

  • Define exception boundaries at controllers, workers, and CLI entry points.
  • Test failure paths as well as successful calls.
  • Use exception chaining when adding domain context.

Web server / environment notes

cli, fpm, apache. An uncaught exception terminates the current request or command.

Tags: cli,fpm,apache

Categories