getPrevious()

Introduction

Exception::getPrevious() returns the exception that was passed as the third argument to a PHP exception constructor — the exception that caused the current one. It is defined on the base Exception (and Error) class, so every PHP exception type inherits it.

This page covers what getPrevious() returns, how to build a chain of "wrapped" exceptions, how to walk that chain, and the common mistakes to avoid.

Syntax and return value

final public Throwable::getPrevious(): ?Throwable

• Parameters: none.
• Returns: the previous Throwable (an Exception or Error) if one was set, otherwise null.
• The method is final, so you cannot override it in your own exception subclasses.

The "previous" exception is set when you construct an exception with a third argument:

throw new RuntimeException("High-level failure", 0, $originalException);
//                          message            ^code  ^previous

Basic example

When you re-throw an exception, pass the original one as the third constructor argument so the context is not lost:

<?php
try {
    try {
        throw new Exception("Inner error");
    } catch (Exception $inner) {
        // Wrap the low-level error in a more meaningful one,
        // keeping the original as "previous".
        throw new Exception("Outer error", 0, $inner);
    }
} catch (Exception $e) {
    echo "Caught: " . $e->getMessage() . "\n";

    $previous = $e->getPrevious();
    if ($previous !== null) {
        echo "Caused by: " . $previous->getMessage() . "\n";
    }
}
?>

Output:

Caught: Outer error
Caused by: Inner error

getPrevious() returns the $inner object you passed in, so you can read its message, code or stack trace exactly as you would for any exception.

Why wrap exceptions at all

A common pattern is to catch a low-level, technical exception (a failed database query, a missing file) and re-throw a higher-level, domain-specific one — without throwing away the original cause:

<?php
function loadUser(int $id): array
{
    try {
        // Pretend this talks to a database and fails.
        throw new RuntimeException("SQLSTATE[HY000]: connection refused");
    } catch (RuntimeException $dbError) {
        // Callers care about "could not load user", not SQL internals,
        // but we keep the SQL error available via getPrevious().
        throw new RuntimeException("Unable to load user #$id", 0, $dbError);
    }
}

try {
    loadUser(42);
} catch (RuntimeException $e) {
    echo $e->getMessage() . "\n";
    echo "Root cause: " . $e->getPrevious()->getMessage() . "\n";
}
?>

Output:

Unable to load user #42
Root cause: SQLSTATE[HY000]: connection refused

This keeps your high-level error messages clean while preserving the technical detail for logging and debugging.

Walking the full exception chain

A previous exception can itself have a previous exception. To inspect the whole chain, loop while getPrevious() returns a non-null value:

<?php
$a = new Exception("Level 1: low-level cause");
$b = new Exception("Level 2: mid-level wrapper", 0, $a);
$c = new Exception("Level 3: top-level error", 0, $b);

$current = $c;
while ($current !== null) {
    echo $current->getMessage() . "\n";
    $current = $current->getPrevious();
}
?>

Output:

Level 3: top-level error
Level 2: mid-level wrapper
Level 1: low-level cause

Common gotchas

• No previous exception returns null. If you create an exception without a third argument, getPrevious() returns null. Always guard with !== null (or a loop) before calling methods on the result.
• The third constructor argument is the previous one, not the code. The signature is new Exception($message, $code, $previous). A frequent mistake is passing the previous exception in the second slot, where PHP expects an integer code.
• It is read-only. There is no setPrevious(). The chain is fixed at construction time, so you must pass the cause when you create the wrapping exception.
• var_dump($e) already shows the chain. When you cast an uncaught exception to a string (or let PHP print it), the "Caused by" / previous-exception trace is included automatically — getPrevious() is for when you need to inspect it in code.

Related methods

getPrevious() is one of several inspection methods every PHP exception exposes:

• getMessage() — the human-readable error message.
• getCode() — the numeric error code.
• getTrace() — the stack trace as an array.
• getTraceAsString() — the stack trace as a string.

For the bigger picture of try/catch and custom exception classes, see PHP Exceptions.

Summary

getPrevious() retrieves the exception that caused the current one, enabling exception chaining: catch a low-level error, throw a meaningful high-level one, and still keep the original root cause for debugging. It returns null when no previous exception was set, so check for that — or loop on it — before using the result.

Practice