When this matters
Read the diagnostic phase before changing code. A reader error asks you to repair spelling, a normalization error asks you to repair form shape, and a runtime error describes a valid form that failed while running.
See it run
LISPEX
(guard (e (else (error-object-message e))) (car 1))Observed result
OUTPUT
"car: expected a pair, got 1"Read the example
car receives 1 instead of a pair and raises a catchable runtime error. guard catches the error object and returns its stable message. The program therefore succeeds with a string rather than printing a host stack trace.
How to reason about it
- Runtime errors use E3xx codes, stable templates, deterministic irritant rendering, and the enclosing call-site span.
- Warnings are ordered observations. A genuine
%call emits W330 before usingmodulo; genuinelist-firstandlist-restcalls emit W331 before usingcarandcdr. Each source call site warns once, a shadowing binding does not warn, and a warning remains recorded if the operation then fails. - The first uncaught error aborts without a host stack trace; resource exhaustion remains outside catchable E3xx.
Choose quickly
| Class | When it appears | First action |
|---|---|---|
| E1xx reader | source cannot become a datum | repair the highlighted token or delimiter |
| E2xx normalization | a form has an invalid static shape | check form spelling, placement, and arity |
| E3xx runtime | evaluation reaches an invalid operation | inspect the named procedure and irritants |
| W3xx warning | execution continues with a deprecated surface | move to the named replacement |
| resource outcome | a profile ceiling is reached | reduce work or choose the correct declared profile |
A common mistake
A warning is not stdout and must not be reordered or merged into a diagnostic.
Use modulo, first, and rest in new code. The deprecated spellings remain
executable only for compatibility.
Current boundaries
- Platform panic, blank crash, and nondeterministic host text are not valid guest diagnostics.
Keep going
Diagnostic Catalog is the exact code lookup. The errors guide shows how to validate before producing a decision.