Error Handling

FOL does not center error handling around exceptions.

This section distinguishes two broad error categories:

• breaking errors: unrecoverable failures, typically associated with panic
• recoverable errors: errors that can be propagated or handled, typically associated with report

The detailed chapters explain:

• how each category behaves
• how routines expose recoverable error types
• how error-aware forms interact with control flow and pipes
• how the current compiler reports syntax, package, and resolver failures

Current compiler diagnostics

The current compiler surface guarantees the following reporting behaviors across the active parser/package/resolver/typecheck/lower/backend chain:

• every diagnostic carries a stable code shown in brackets (e.g. error[R1003]:)
• all failures keep exact primary file:line:column locations
• human-readable diagnostics render source snippets and underline the primary span
• related sites such as duplicate declarations or ambiguity candidates appear as secondary labels
• JSON diagnostics preserve the same structured information with labels, notes, helps, and stable producer-owned diagnostic codes
• the parser recovers after failed declarations instead of cascading errors
• duplicate diagnostics on the same line are suppressed, with a hard cap at 50
• LSP diagnostics are deduplicated by line and code before reaching the editor

The exact wording of messages is still implementation detail, but the current compiler contract is that locations, codes, and structured diagnostic shape are stable enough to build tests and tooling around them.

For the detailed compiler-facing reporting model, see Compiler Diagnostics.