---
name: Perl diagnostic messages
---
# Diagnostic messages

When a program goes wrong, Perl tells you about it. Some
diagnostics stop the program (`die`-style fatal errors); others
print a line to `STDERR` and let it run on (warnings). This
reference lists the diagnostics PetaPerl emits, grouped by where
they come from, with the cause and the fix for each.

Every entry shows the **message verbatim** in a code span - the
exact text the interpreter prints, with the placeholders (`%s`,
`%d`, a named variable) shown the way they appear in the output.
Search this page for the literal words you saw on `STDERR` and you
will land on the entry.

## Reading an entry

Each entry opens with the message text, then a short
classification badge in parentheses, then the cause and the fix:

> `` `Illegal division by zero` ``   **(F)**
> You divided by zero. Guard the divisor.

The badge follows the same letter code Perl has always used:

| Code | Meaning                                                        |
|------|---------------------------------------------------------------|
| **W** | A warning - printed only when warnings are enabled. Optionally restricted to a category (shown as `(W category)`). |
| **D** | A deprecation - a warning that a feature is on the way out.    |
| **S** | A severe warning - on by default, but still only a warning.    |
| **F** | A fatal error - the program dies unless the error is trapped (`eval`, `try`). |
| **P** | An internal error (a panic) - should never reach a user. If you see one, it is a bug in pperl. |
| **X** | A very fatal error - the program exits immediately.           |
| **A** | An alien error - produced by something other than Perl itself. |

## Enabling and silencing warnings

Warnings (the **W**, **D**, and **S** classes) are controlled by
the `warnings` pragma. Without it, only the
severe (**S**) warnings print:

```perl
use warnings;                    # turn on every warning
no warnings;                     # turn them all off (lexically)
no warnings 'uninitialized';     # turn off one category
use warnings FATAL => 'all';     # promote warnings to fatal errors
```

The category named in a `(W category)` badge is the string you
pass to `no warnings` to silence just that diagnostic. A single
`$SIG{__WARN__}` handler can intercept every warning at runtime;
`$SIG{__DIE__}` does the same for fatal errors. See
[`%SIG`](perlvar/signals).

## A note on portability

PetaPerl runs only on Linux and ships no XS layer. The platform
diagnostic families a portable perl carries - VMS status codes,
Win32 `GetLastError` text, "unimplemented on this architecture"
notices, XS-loader failures - therefore do not arise here. Where
upstream Perl documents a diagnostic that only fires on another
operating system or through XS, PetaPerl simply never emits it.

## The diagnostics

```{toctree}
:maxdepth: 1

perldiag/fatal-general
perldiag/fatal-regex
perldiag/fatal-syntax
perldiag/warnings
perldiag/value-and-types
perldiag/internal
perldiag/pperl-specific
```

- [General fatal errors](perldiag/fatal-general) - method
  resolution, references, arithmetic, restricted hashes,
  filehandles, and the rest of the runtime `die`s that are not
  regex- or parser-specific.
- [Regex compilation errors](perldiag/fatal-regex) - everything
  the pattern compiler rejects, from `Unmatched )` to malformed
  `\g`, `\N`, `\o`, and `(?...)` constructs.
- [Compile-time syntax errors](perldiag/fatal-syntax) - errors
  the parser and codegen raise before the program runs.
- [Warnings](perldiag/warnings) - the non-fatal diagnostics:
  deep recursion, wide characters, useless constructs.
- [Value and type errors](perldiag/value-and-types) - diagnostics
  about what a value is and is not: not a reference, not a code
  reference, division by zero, restricted-hash access.
- [Internal errors](perldiag/internal) - the panics that signal a
  bug in pperl itself.
- [pperl-specific diagnostics](perldiag/pperl-specific) -
  messages PetaPerl emits that have no upstream Perl counterpart.