# Error codes

URL: /docs/errors
Markdown: /docs/errors.md

> Every Sakura Lang diagnostic code with its explanation, a program that triggers it and the fixed program.

Every diagnostic code the compiler and the runtime report, with its explanation, a program that triggers it and, where one is checked in, the fixed program. Codes are stable and never renumbered (design §12.3); `sakura explain <code>` prints the same explanation offline, and a diagnostic's `explanation_uri` (`sakura://explain/<code>`) maps to `/docs/errors/<code>`. `V` codes are errors, `W` warnings and `D` runtime defects; the [diagnostics reference](/docs/agents/diagnostics) describes the JSON records.

90 codes; 64 pages show a fixed program that the compiler's test suite checks.

## Lex and parse [#lex-and-parse]

| Code | Title | Summary |
| --- | --- | --- |
| [V0001](/docs/errors/V0001) | `syntax_error` | The parser expected a different token, or a delimiter was never closed. |
| [V0002](/docs/errors/V0002) | `unterminated` | A string literal, interpolation or block comment reaches the end of the file without being closed. |
| [V0003](/docs/errors/V0003) | `int_literal_out_of_range` | An `Int` literal is outside the 64-bit signed range `[-2^63, 2^63-1]` (design §2.2). |
| [V0004](/docs/errors/V0004) | `invalid_character` | The source contains a character that cannot start any token. |
| [V0005](/docs/errors/V0005) | `invalid_escape` | A string contains an escape that is not one of `\\ \" \n \r \t \0 \{ \}` or `\u{XXXXXX}` (design §2.3). |
| [V0006](/docs/errors/V0006) | `malformed_number` | A numeric literal is malformed, such as `0x` with no digits, `1.` or `.5`. |
| [V0007](/docs/errors/V0007) | `reserved_keyword` | The word is reserved for a future edition: `verify proof ghost control resume region spawn actor interface impl` (design §2.1). |
| [V0008](/docs/errors/V0008) | `nesting_limit_exceeded` | Expressions, types, patterns or blocks nest deeper than the parser's limit (128). |
| [V0009](/docs/errors/V0009) | `expected_terminator` | Two statements are on one line without `;`, or junk follows a complete statement (design §2.4). |
| [V0010](/docs/errors/V0010) | `chained_comparison` | Comparison operators do not chain (design §3.1). |
| [V0011](/docs/errors/V0011) | `call_site_type_arguments` | Expressions cannot take type arguments in v0 (design §3.2). |
| [V0012](/docs/errors/V0012) | `keyword_expression_operand` | `if`, `match`, `with`, `try`, `fn`, `handler` and `fail` expressions cannot be operands of a binary or postfix operator without parentheses (design §3.2). |
| [V0013](/docs/errors/V0013) | `invalid_assign_target` | The left side of `=` must be a `var` name or a field path on one (`u.email = e`). |
| [V0014](/docs/errors/V0014) | `named_argument` | Calls take positional arguments only (design §3.2 rule 13, §17.21); `name: value` exists only inside attribute arguments. |

## Names and modules [#names-and-modules]

| Code | Title | Summary |
| --- | --- | --- |
| [V1001](/docs/errors/V1001) | `duplicate_definition` | Two items in the same module and namespace have the same name (design §9). |
| [V1002](/docs/errors/V1002) | `unresolved_name` | No value with this name is in scope. |
| [V1003](/docs/errors/V1003) | `unresolved_type` | No type, effect, variant or error tag with this name is in scope. |
| [V1004](/docs/errors/V1004) | `name_case_mismatch` | Values are `lower_snake` identifiers and types, variants, error tags and effects are `UpperCamel` (design §2.1). |
| [V1005](/docs/errors/V1005) | `unresolved_module` | An `import` names a module that does not exist in the snapshot, std, or the declared dependencies. |
| [V1006](/docs/errors/V1006) | `private_item` | The item exists but this module cannot use it: it is not `pub`, or it is a constructor or field of a `pub opaque` type, which only the declaring module may use (design §9, §17.10). |
| [V1007](/docs/errors/V1007) | `wrong_kind` | A name resolved to the wrong kind of item for where it is used: an effect where a type is expected, a type where a value is expected, and so on. |
| [V1010](/docs/errors/V1010) | `unknown_attribute` | Only these attributes exist in v0: `@tool`, `@llm`, `@external`, `@total`, `@contract_test`, `@deprecated`, `@server`, `@test_only` on items, and `@trust("reason")` as an expression (design §2.5). |
| [V1011](/docs/errors/V1011) | `missing_body` | A function has no body. |
| [V1012](/docs/errors/V1012) | `mixed_union_alternatives` | `type X = A \| B` must be either all existing error tags (an error-union alias) or all new variants. |
| [V1020](/docs/errors/V1020) | `recursive_lambda` | Local lambdas cannot refer to themselves. |
| [V1030](/docs/errors/V1030) | `import_cycle` | Modules import each other in a cycle; v0 forbids import cycles (design §9). |
| [V1040](/docs/errors/V1040) | `assign_immutable` | Only `var` bindings can be assigned; `let` bindings and parameters are immutable (design §8.1). |
| [V1041](/docs/errors/V1041) | `jump_outside_loop` | `break` or `continue` appears outside a `for` or `while` loop (or crosses a function boundary: a `break` inside a lambda cannot leave the loop around the lambda). |

## Types [#types]

| Code | Title | Summary |
| --- | --- | --- |
| [V2001](/docs/errors/V2001) | `type_mismatch` | An expression has a different type from the one its context requires. |
| [V2002](/docs/errors/V2002) | `arity_mismatch` | A function was called with the wrong number of arguments, or a pattern has the wrong number of fields. |
| [V2003](/docs/errors/V2003) | `not_callable` | The callee of a call expression is not a function: a value of another type is followed by `(…)`. |
| [V2004](/docs/errors/V2004) | `unknown_field` | The record type has no field with this name, or a record literal is missing required fields or names an extra one. |
| [V2005](/docs/errors/V2005) | `infinite_type` | Inference would need a type that contains itself (the occurs check failed). |
| [V2010](/docs/errors/V2010) | `cannot_infer_type` | The type of an empty collection literal (or another binding) cannot be inferred from its uses. |
| [V2015](/docs/errors/V2015) | `error_union_annotation_needed` | Two different error unions meet in synthesis mode (for example the branches of an `if`). |
| [V2031](/docs/errors/V2031) | `not_show` | A value whose type is not `Show` was interpolated or printed. |
| [V2032](/docs/errors/V2032) | `constraint_not_satisfied` | A type does not satisfy a constraint the operation requires: `Eq`, `Ord`, `Hash` or `Schema` (`Show` is `V2031`). |
| [V2033](/docs/errors/V2033) | `opaque_not_schema` | A `Schema` bound (`Json.decode`, `Sql.query` rows, `Llm.generate`, `Cli.parse`, `Tool.of` arguments, a `property` parameter) reaches an opaque type outside its declaring module, directly or through a field (design §17.130). |
| [V2034](/docs/errors/V2034) | `refined_field_assignment` | A field assignment changes a field of a `var` whose type, or the type of a prefix of the path, is a refined type (design §17.135). |
| [V2040](/docs/errors/V2040) | `unused_value` | A non-final expression statement produces a non-`Unit` value that is dropped. |
| [V2041](/docs/errors/V2041) | `assign_captured_var` | A lambda, or a `try` body, assigns to a `var` declared outside it. |
| [V2050](/docs/errors/V2050) | `hole_in_build` | `sakura build`, `sakura run` and `sakura test` reject typed holes (`?name`). |

## Effects and handlers [#effects-and-handlers]

| Code | Title | Summary |
| --- | --- | --- |
| [V3001](/docs/errors/V3001) | `effect_not_allowed` | The body performs an effect that the function's signature does not allow. |
| [V3002](/docs/errors/V3002) | `effect_label_not_permitted` | A closed effect row was required to be empty or smaller, but an effect label had to be in it (row unification `{A \| r} ~ {}` failed, design §5.2). |
| [V3003](/docs/errors/V3003) | `try_unknown_failures` | `try` without `catch` must name every failure of its body in `Result<T, E>`. |
| [V3010](/docs/errors/V3010) | `invalid_operation_row` | An effect operation's row may contain only `Fail<…>` in v0 (design §5.5). |
| [V3011](/docs/errors/V3011) | `handler_clause_mismatch` | A `handler` must provide exactly one clause per operation of its effect, with matching parameter counts (design §5.5). |
| [V3012](/docs/errors/V3012) | `with_non_handler` | `with` was given something that is not a `Handler<E, r>` value. |
| [V3020](/docs/errors/V3020) | `test_unhandled_effect` | Tests run under deterministic default handlers for `Clock`, `Random`, `Env`, `Console` and `Log` (design §5.8). |

## Patterns [#patterns]

| Code | Title | Summary |
| --- | --- | --- |
| [V4001](/docs/errors/V4001) | `non_exhaustive_match` | A `match` does not cover every value. |
| [V4002](/docs/errors/V4002) | `unreachable_arm` | A `match` arm can never be reached because earlier arms already cover every value it matches. |
| [V4003](/docs/errors/V4003) | `or_pattern_bindings` | All alternatives of an or-pattern must bind the same names with the same types (design §3.2). |

## Contracts and refinements [#contracts-and-refinements]

| Code | Title | Summary |
| --- | --- | --- |
| [V5001](/docs/errors/V5001) | `impure_contract` | Predicates in `where`, `requires`, `ensures` and `property` bodies must be pure, terminating and deterministic: no loops, no recursion, and calls only to `@total` functions in the contract subset (design §7.1). |
| [V5002](/docs/errors/V5002) | `refinement_checked_at_runtime` (retired) | Retired (design §17.87, §12.3): never reported. |
| [V5003](/docs/errors/V5003) | `validate_target_not_refined` | `Untrusted.validate(u)` takes its target `V` from the expected type `Result<V, Violation>`. |
| [V5004](/docs/errors/V5004) | `literal_violates_refinement` | A literal stands where a refined type is expected, and the compiler evaluated the type's `where` clause on it: the predicate is false, or evaluating it defects (an integer division by zero, a failed `requires` of a function it calls). |

## Capabilities, resources and escape [#capabilities-resources-and-escape]

| Code | Title | Summary |
| --- | --- | --- |
| [V6001](/docs/errors/V6001) | `capability_construction` | Capability values (`Dir`, `NetScope`, `EnvScope`, `SecretStore`) cannot be constructed by user code. |
| [V6002](/docs/errors/V6002) | `scoped_value_escape` | A scoped value escapes the `with` that bounds it (design §6.3, §17.70). |
| [V6003](/docs/errors/V6003) | `resource_escape` | A `@resource` value (v0: `File`) escapes the callback of the operation that introduced it: the callback returns a type containing it (directly, or inside a record, list or closure), or the value is stored in handler `var` state (design §8.4, §17.70). |
| [V6010](/docs/errors/V6010) | `non_std_effect_in_main` | `main`'s effect row may contain only std effects, because only they have host root handlers (design §9). |

## Packages and build [#packages-and-build]

| Code | Title | Summary |
| --- | --- | --- |
| [V8001](/docs/errors/V8001) | `missing_entry_point` | `sakura run` needs `pub fn main() -> Unit ! {…}` in the program it runs (design §9). |
| [V8002](/docs/errors/V8002) | `reserved_package_name` | `sakura.toml` names its package `std` or `main` (design §9, §17.131). |
| [V8003](/docs/errors/V8003) | `abi_version_mismatch` | The WASM module was compiled against a runtime ABI this host does not implement (`runtime/rt/ABI.md` §0): its major version differs, or its minor version is newer than the host's, so it may need imports the host lacks. |
| [V8004](/docs/errors/V8004) | `target_unsupported_external` | A user package declares an `@external(js, …)` function, and `--target wasm` has no JavaScript to call (design §17.81): the WASM backend runs std's host operations through the runtime's own imports only. |
| [V8020](/docs/errors/V8020) | `spec_frozen` | A patch modifies a frozen symbol's signature, effect row, error union, contracts, or a test body (design §7.3). |

## Internal [#internal]

| Code | Title | Summary |
| --- | --- | --- |
| [V9001](/docs/errors/V9001) | `internal_error` | The compiler hit a bug. |
| [V9002](/docs/errors/V9002) | `phase_unavailable` | A compiler phase needed by this command is not implemented yet in this pre-alpha build. |

## Warnings [#warnings]

| Code | Title | Summary |
| --- | --- | --- |
| [W1002](/docs/errors/W1002) | `shadowed_import` | A local binding shadows an imported name. |
| [W4010](/docs/errors/W4010) | `catch_all_on_open_union` | A `catch` uses `_ => …` on an error union that may grow. |
| [W5005](/docs/errors/W5005) | `linear_contract_on_hot_path` | A `requires`, `ensures`, `where` or `property requires` clause calls `List.all`, `List.any`, `List.contains` or `String.contains` on a parameter (or `it`), so every check scans the whole value (design §7.2, §17.72). |
| [W7001](/docs/errors/W7001) | `property_discard_budget` | A property discarded more than 90% of its generated inputs, so it tested almost nothing (design §7.4, §17.64). |
| [W7002](/docs/errors/W7002) | `vacuous_obligation` | A contract obligation was proved only because the assumptions on its path are contradictory, so the path can never run and the proof says nothing useful (design §17.98, §17.105). |
| [W8001](/docs/errors/W8001) | `copy_on_write` | An update to a shared collection is forced to copy inside a loop because another reference retains the old value (design §8.2). |

## Runtime defects [#runtime-defects]

| Code | Title | Summary |
| --- | --- | --- |
| [D001](/docs/errors/D001) | `int_overflow` | Checked `Int` arithmetic overflowed 64 bits. |
| [D002](/docs/errors/D002) | `division_by_zero` | `/` or `%` was evaluated with a divisor of `0`. |
| [D003](/docs/errors/D003) | `int_beyond_js_safe_range` | On the JS backend, an `Int` left the exactly representable range ±(2^53−1). |
| [D004](/docs/errors/D004) | `float_not_finite` | `Float.round` or a float-to-int conversion was given NaN or ±∞. |
| [D010](/docs/errors/D010) | `refinement_violated` | A checked introduction such as `Email.from(s)` received a value that fails the refinement. |
| [D011](/docs/errors/D011) | `contract_evaluation_failed` | Evaluating a contract predicate itself defected (for example it overflowed). |
| [D020](/docs/errors/D020) | `precondition_violated` | A `requires` clause failed on entry. |
| [D021](/docs/errors/D021) | `postcondition_violated` | An `ensures` clause failed on normal return. |
| [D030](/docs/errors/D030) | `option_expect_none` | `Option.expect` was called on `None`. |
| [D031](/docs/errors/D031) | `string_slice_not_char_boundary` | `String.slice` was given a byte offset that is not on a UTF-8 character boundary. |
| [D090](/docs/errors/D090) | `runtime_internal_error` | The runtime hit a bug or an exhausted host resource (for example a JS exception that is not a Sakura Lang defect). |
| [D091](/docs/errors/D091) | `host_failure` | A host operation failed outside Sakura Lang's control (for example a rejected host promise). |
| [D092](/docs/errors/D092) | `rc_overflow` | On the WASM runtime, an object's reference count would pass 2^32 − 1. |
| [D093](/docs/errors/D093) | `finalizer_failed` | On the WASM runtime, a finalizer (the cleanup of `Fs.with_file` and similar) failed with an error. |
| [D094](/docs/errors/D094) | `context_escaped` | On the WASM runtime, an operation callback was called after its handler's perform site was gone. |
| [D095](/docs/errors/D095) | `fiber_retired` | On the WASM runtime, `join` was called on a fiber that had already been retired. |
| [D096](/docs/errors/D096) | `heap_exhausted` | On the WASM runtime, the heap limit (`SAKURA_MAX_HEAP`) was reached or memory could not grow. |