---
name: die
signature: 'die LIST'
since: 5.0
status: documented
categories: ["I/O", "Control flow"]
---

```{index} single: die; Perl built-in
```

*[I/O](../perlfunc-by-category) · [Control flow](../perlfunc-by-category)*

# die

Raise an exception.

`die` throws an exception built from `LIST`. If the exception happens
inside an [`eval`](eval), the [`eval`](eval) terminates with [`undef`](undef) and [`$@`](../perlvar) holds
the exception value. If nothing catches it, Perl prints the message
to `STDERR` and the interpreter exits with a non-zero status. The
exception can be a plain string, a list that stringifies into one,
or a reference — typically a blessed object carrying structured
error state.

## Synopsis

```perl
die LIST
die $message
die $exception_object
die                         # re-raise / propagate current $@
```

## What you get back

`die` does not return. Control transfers to the nearest dynamically
enclosing [`eval`](eval) (which then returns [`undef`](undef) in scalar context or
the empty list in list context), or — if there is no enclosing
[`eval`](eval) — the interpreter unwinds, runs `END` and `DESTROY` handlers,
and exits.

The exception value itself lands in [`$@`](../perlvar):

- **String exceptions** — the stringified message, including any
  appended `at FILE line N.\n` (see below).
- **Reference exceptions** — the reference itself, unchanged. This
  is the idiomatic way to throw a blessed exception object.

On uncaught exit, the exit code is derived from [`$!`](../perlvar) and [`$?`](../perlvar):

```perl
exit $! if $!;              # errno
exit $? >> 8 if $? >> 8;    # child exit status
exit 255;                   # last resort
```

Rely only on the exit code being non-zero; the exact value is a
best-effort encoding of whatever global error state was live at the
moment of the throw.

## Global state it touches

- [`$@`](../perlvar) — written with the exception on unwind into an
  [`eval`](eval), read by the no-argument form of `die` to propagate an
  existing exception, and read by the uncaught-exception printer.
- [`$!`](../perlvar) — read when deriving an exit code for an
  uncaught exception, and commonly interpolated into the message
  itself (`die "open $f: $!"`).
- [`$?`](../perlvar) — read when deriving an exit code if [`$!`](../perlvar) is
  zero. `END` and `DESTROY` handlers can still mutate it before the
  process actually exits.
- [`$.`](../perlvar) — the current input line number, appended to
  string exceptions that lack a trailing newline.
- [`$SIG{__DIE__}`](../perlvar) — if set, the handler runs *before*
  the exception is propagated, with the exception as its argument.
  The handler can replace the exception by calling `die` again with
  a different value.
- [`$^S`](../perlvar) — readable by `$SIG{__DIE__}` handlers to tell
  whether the die is happening inside an [`eval`](eval).

## The trailing-newline rule

Whether `die` appends location information depends on one character
at the end of the message:

- **Message ends in `"\n"`** — used verbatim. Nothing is appended.
  Use this form when the message is already a complete, user-facing
  diagnostic.
- **Message does not end in `"\n"`** — Perl appends
  `" at FILE line N"`, and if a file is being read,
  `", <HANDLE> line M"`, then a final `"."` and newline. Use this
  form during development, or whenever locating the `die` call in
  the source is more useful than a tidy message.

```perl
die "bad config\n";                 # "bad config\n"
die "bad config";                   # "bad config at script.pl line 42.\n"
```

A common idiom is to append `", stopped"` to make the location
suffix read naturally:

```perl
die "/etc/games is no good, stopped";
# /etc/games is no good, stopped at canasta line 123.
```

Reference exceptions never get location information appended —
stringifying an object to inspect it would defeat the point of
throwing an object. If you want file and line inside a structured
exception, capture them at construction time (`__FILE__`,
`__LINE__`, or [`caller`](caller)).

## Reference-valued exceptions

Passing a reference — typically a blessed object — lets [`$@`](../perlvar) carry
structured state instead of a string you later have to parse:

```perl
package MyApp::Error;
sub new   { my ($c, %a) = @_; bless { %a }, $c }
sub code  { $_[0]{code}  }
sub where { $_[0]{where} }

eval {
    die MyApp::Error->new(code => 'EPARSE', where => 'line 12');
};
if (my $err = $@) {
    if (ref($err) && $err->isa('MyApp::Error')) {
        warn "parse error at ", $err->where;
    }
    else {
        die $err;   # not ours — re-raise
    }
}
```

Overload stringification on exception classes so that an uncaught
exception still prints a useful message:

```perl
use overload '""' => sub { "[MyApp::Error ".$_[0]->code."]\n" };
```

The stringified form should end in a newline and be non-empty,
matching the treatment of string exceptions.

Because [`$@`](../perlvar) is a global, copy it into a lexical before inspecting
it — any method call, [`ref`](ref), or `isa` you run during handling can
itself [`eval`](eval) internally and clobber [`$@`](../perlvar):

```perl
if (my $err = $@) { ... }       # safe
if ($@) { $@->method; ... }     # unsafe: method may reset $@
```

## Propagation: `die` with no argument (or empty string)

When `LIST` is empty or stringifies to `""`, `die` does not throw a
fresh exception — it re-raises whatever is in [`$@`](../perlvar):

- If [`$@`](../perlvar) holds a **string**, `die` appends `"\t...propagated at
  FILE line N.\n"` and re-throws. This is the canonical way to let
  an exception continue up the call stack after a partial-match
  check:

  ```perl
  eval { risky() };
  die unless $@ =~ /Expected exception/;
  ```

- If [`$@`](../perlvar) holds an **object reference with a `PROPAGATE` method**,
  that method is invoked as
  `$@ = eval { $@->PROPAGATE(__FILE__, __LINE__) }`, and the return
  value replaces [`$@`](../perlvar) before the re-throw. Implement `PROPAGATE` on
  an exception class when you want the exception to record the
  chain of re-raises.

- If [`$@`](../perlvar) holds an object reference with **no** `PROPAGATE`, the
  reference is re-thrown unchanged.

- If [`$@`](../perlvar) is also empty, the string `"Died"` is used.

## The `$SIG{__DIE__}` hook

Setting `$SIG{__DIE__}` installs a handler that runs when `die`
fires, with the exception as its argument. The handler can inspect
or replace the exception by calling `die` again with a different
value. It runs **even inside [`eval`](eval)**, which is the usual reason to
want it out of the way:

```perl
local $SIG{__DIE__} = sub {
    die @_ if $^S;              # inside eval: do nothing special
    log_fatal(@_);              # outside eval: log before we exit
};
```

`$^S` is [`undef`](undef) during compilation, true inside an [`eval`](eval), and
false at the top level — use it to gate handler work that only
makes sense for uncaught exceptions.

## Examples

Bail out with a clean message (note the trailing newline suppresses
file/line appending):

```perl
chdir '/var/spool' or die "can't cd to spool: $!\n";
```

Die without a newline during development so the location is
appended:

```perl
die "unexpected empty record";
# unexpected empty record at parse.pl line 87.
```

Catch a string exception:

```perl
eval {
    parse($input);
};
if ($@) {
    warn "parse failed: $@";    # $@ already ends in "\n" if the
                                # die'd message did
}
```

Throw and catch a blessed exception object:

```perl
eval {
    die MyApp::Error->new(code => 'EIO', detail => $!);
};
if (my $err = $@) {
    if (ref($err) && $err->isa('MyApp::Error')) {
        handle($err);
    }
    else {
        die $err;               # re-raise anything unexpected
    }
}
```

Conditional propagation — catch one class, let the rest through:

```perl
eval { work() };
die unless $@ =~ /^recoverable:/;
recover();
```

## Edge cases

- **List with two or more items** is stringified and concatenated to
  form the message: `die "read failed on ", $file, ": $!"`. The
  newline rule applies to the concatenated result.
- **Empty list** (`die;` or `die "";`) triggers the propagation
  path described above, not a fresh exception.
- **Reference with trailing newline inside the stringified form**
  is irrelevant: location is never appended to a reference, regardless
  of what its `""` overload produces.
- **`die` inside `DESTROY` during global destruction** can still
  fire `$SIG{__DIE__}` but may not propagate as expected — the
  interpreter is already unwinding. Keep destructors defensive.
- **Uncaught `die` during `END` block** runs remaining `END`
  blocks but sets exit status per the [`$!`](../perlvar)/[`$?`](../perlvar) rule above.
- **Nested [`eval`](eval) and `$SIG{__DIE__}`**: the handler runs for
  *every* die, including those caught by an inner [`eval`](eval). Guard
  with `$^S` if the handler has side effects.
- **Re-throwing the current [`$@`](../perlvar)**: prefer bare `die;` over
  `die $@;`. The bare form triggers the propagation machinery
  (`...propagated` suffix, `PROPAGATE` hook); `die $@` does not —
  it treats [`$@`](../perlvar) as a fresh exception value.

## Differences from upstream

Fully compatible with upstream Perl 5.42.

## See also

- [`eval`](eval) — the only construct that catches a `die`; its
  block form traps exceptions into [`$@`](../perlvar)
- [`warn`](warn) — same formatting rules (trailing-newline
  suppresses location), but writes to `STDERR` and does not unwind
- [`caller`](caller) — capture file and line at throw time when
  building a structured exception object
- [`exit`](exit) — use when you want a specific exit code without
  the exception-handling machinery
- [`$@`](../perlvar) — where the exception lands after an [`eval`](eval)
  catches it, and the source the no-arg `die` re-raises from
- [`$SIG{__DIE__}`](../perlvar) — pre-throw hook that can inspect
  or rewrite the exception
- [`$^S`](../perlvar) — tells a `$SIG{__DIE__}` handler whether it
  is running inside an [`eval`](eval)