Read a diagnostic's code and source location to decide what to fix. The stage tells you whether the error occurred before execution or can reach a runtime handler.
The command below uses the native lispex installation from Getting Started.
Read a runtime diagnostic
Save this complete program as pair.lspx.
(car 1)lispex run pair.lspxThe command leaves standard output empty, writes the following to standard error, and exits with status 1. It creates no output file.
E310 pair.lspx:1:1 car: expected a pair, got 1| Part | What it tells you |
|---|---|
E310 | An operation expected a pair. |
pair.lspx:1:1 | Inspect line 1, column 1 of this file. |
car: expected a pair, got 1 | car received the number 1. Check its argument. |
To return the first item, replace 1 with a pair, such as '(1 2). The complete expression (car '(1 2)) returns 1.
To handle the failure instead, paste this complete example into the Playground.
(guard (e (else (error-object-message e))) (car 1))Result
"car: expected a pair, got 1"Here guard catches the error object and returns its message as a string. The expression succeeds.
Find the stage and next action
The reader turns source text into values and forms. Normalization checks form structure and rewrites shorthand into core forms. Both happen before execution.
| Stage and codes | What to inspect | Can a handler run? |
|---|---|---|
| Reader · E100, E140, E150 | Tokens, parentheses, dotted lists, string and character escapes | No. Repair the source. |
| Normalization · E110, E130 | Reserved names and the required parts of each form | No. Repair the binding or form. |
| Reader or normalization · E120 | A forbidden extension or form | No. Use syntax supported by the language profile. |
| Runtime · E300–E340 | The named operation and the values it received | Runtime faults can be handled. See the E314 exception below. |
| Runtime warnings · W330, W331 | A deprecated procedure name | Execution continues. Use the suggested replacement. |
Resource limit · ResourceLimit | Work required by the program and its resource profile | No. Resource exhaustion ends the run outside catchable E3xx errors. |
E314 needs a stage check. The literal 1e999 fails while being read, even inside guard. Overflow from (* 1e308 1e308) occurs during execution and can be caught.
Runtime diagnostics use fixed message templates and consistent printed values. Most point to the enclosing call. E300 points to the unbound name itself, so (+ 1 missing) points to missing at column 6.
The first uncaught error stops execution. Lispex reports the source diagnostic without a host stack trace. A crash in the calling application must be investigated as an application failure.
Read warnings separately from results
A warning reports a deprecated name while the operation still runs. For example, save this complete program as warning.lspx.
(% 7 3)lispex run warning.lspxStandard output contains the result.
1Standard error contains the warning.
W330 warning.lspx:1:1 `%` is a deprecated alias of `modulo` — prefer `modulo`The exit status is 0, and no output file is created. Replace % with modulo to keep the result and remove this warning.
| Deprecated name | Use in new code | Operation performed |
|---|---|---|
% | modulo | modulo |
list-first | first | car |
list-rest | rest | cdr |
A genuine deprecated procedure call warns once per source call site, before performing its operation. If your program binds that name to another procedure, calling it does not produce the alias warning.
Keep warnings in occurrence order and separate from standard output and the error diagnostic. If the operation fails, its warning remains recorded. For example, (list-first 1) produces W331 followed by E310.