Find the code you saw to identify what to inspect next. Check its stage before deciding whether to use an exception handler.
Start with the code
For example, this complete expression fails during execution.
(car 1)Code and message
E310 · car: expected a pair, got 1The E310 row below tells you to check the argument to car. Passing a pair, as in (car '(1 2)), returns 1. The diagnostics manual shows the full file, command, and diagnostic location.
Fix source errors before execution
Handlers have not started at these stages. Repair the source and run it again.
| Code | Stage | What to inspect |
|---|---|---|
| E100 | Reader | An invalid token or unmatched delimiter, such as the missing ) in (+ 1 2. |
| E110 | Normalization | A binding that uses a reserved word, such as if. Choose another name. |
| E120 | Reader or normalization | A forbidden extension or form, such as #; or define-syntax. |
| E130 | Normalization | A malformed form. Check its required parts, such as all three expressions in if. |
| E140 | Reader | A malformed dotted list. Check the dot and the value after it. |
| E150 | Reader | An invalid string escape or character literal. |
| E314 | Reader | A non-finite inexact number literal, such as 1e999. |
The reader turns source text into values and forms. Normalization checks form structure and rewrites shorthand into core forms.
Fix or catch runtime errors
These errors arise when execution reaches the failing operation. A guard can handle them; its selected clause returns a result from the guard expression.
| Code | Cause | What to inspect |
|---|---|---|
| E300 | Reading an unbound name | The name at the reported source position and its definition. |
| E301 | Calling a value that is not a procedure | The value in the procedure position of the call. |
| E302 | Wrong number of arguments | The procedure's parameters and the number of arguments supplied. |
| E303 | set! targets an unbound name | Whether the name has a binding before assignment. |
| E310 | An operation expected a pair or suitable list | The argument passed to car, cdr, or the named list procedure. |
| E311 | An index is out of range | The index and the size of the value being accessed. |
| E312 | A built-in procedure received the wrong type | The types accepted by the named procedure. |
| E313 | Division by zero | The divisor. |
| E314 | An inexact result is not finite | The arithmetic operation and operand magnitudes. |
| E320 | Wrong number of returned values for the position | Whether the receiving expression expects one value or accepts several. |
| E321 | Reading a letrec binding before initialization | References evaluated while its initial values are being computed. |
| E340 | An escape continuation is no longer active | Whether it has already been used or its owning call has returned. |
E314 during reading cannot be caught. E314 from an arithmetic operation during execution can be caught.
An escape continuation is a procedure created by call/cc to return early from its call. It can be used only once while that call is active.
Handle raised objects and handler errors
| Code | Cause | How handling works |
|---|---|---|
| E330 | (error message …) raises an error object | guard receives the object. Inspect its message and irritants, the extra values attached to the error. |
| E331 | A raised object reaches the top without being handled | Catch it with guard or a handler. raise can carry any value, so check error-object? before reading error-object fields. |
| E332 | A handler returns normally from a non-continuable raise | An outer handler can catch this new error. Use guard to leave the failing expression, or raise-continuable when a handler's return value should resume it. |
If no guard clause matches and there is no else, the original raised object is raised again. raise-continuable returns the handler's result to the raising call. The errors guide shows both kinds of handling.
Update deprecated names
Warnings preserve occurrence order. Each genuine deprecated call warns once per source call site, even if the operation then fails. A binding that shadows the name does not produce that alias warning.
| Code | Call that warns | Use in new code |
|---|---|---|
| W330 | % | modulo |
| W331 | list-first or list-rest | first or rest, respectively |
Respond to a resource limit
ResourceLimit reports a resource outcome separately from catchable E3xx errors. A non-tail call has work left to do after the called procedure returns. When the depth of these calls reaches its limit, the native command reports recursion-limit and exits with status 2.
Reduce the work or review the declared resource profile. An exception handler cannot resume a run stopped by a resource limit.
Read diagnostic locations and output channels · Handle errors