Error codes
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 describes the JSON records.
90 codes; 64 pages show a fixed program that the compiler's test suite checks.
Lex and parse
| Code | Title | Summary |
|---|---|---|
| V0001 | syntax_error | The parser expected a different token, or a delimiter was never closed. |
| V0002 | unterminated | A string literal, interpolation or block comment reaches the end of the file without being closed. |
| 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 | invalid_character | The source contains a character that cannot start any token. |
| V0005 | invalid_escape | A string contains an escape that is not one of \\ \" \n \r \t \0 \{ \} or \u{XXXXXX} (design §2.3). |
| V0006 | malformed_number | A numeric literal is malformed, such as 0x with no digits, 1. or .5. |
| 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 | nesting_limit_exceeded | Expressions, types, patterns or blocks nest deeper than the parser's limit (128). |
| V0009 | expected_terminator | Two statements are on one line without ;, or junk follows a complete statement (design §2.4). |
| V0010 | chained_comparison | Comparison operators do not chain (design §3.1). |
| V0011 | call_site_type_arguments | Expressions cannot take type arguments in v0 (design §3.2). |
| 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 | invalid_assign_target | The left side of = must be a var name or a field path on one (u.email = e). |
| 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
| Code | Title | Summary |
|---|---|---|
| V1001 | duplicate_definition | Two items in the same module and namespace have the same name (design §9). |
| V1002 | unresolved_name | No value with this name is in scope. |
| V1003 | unresolved_type | No type, effect, variant or error tag with this name is in scope. |
| V1004 | name_case_mismatch | Values are lower_snake identifiers and types, variants, error tags and effects are UpperCamel (design §2.1). |
| V1005 | unresolved_module | An import names a module that does not exist in the snapshot, std, or the declared dependencies. |
| 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 | 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 | 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 | missing_body | A function has no body. |
| V1012 | mixed_union_alternatives | type X = A | B must be either all existing error tags (an error-union alias) or all new variants. |
| V1020 | recursive_lambda | Local lambdas cannot refer to themselves. |
| V1030 | import_cycle | Modules import each other in a cycle; v0 forbids import cycles (design §9). |
| V1040 | assign_immutable | Only var bindings can be assigned; let bindings and parameters are immutable (design §8.1). |
| 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
| Code | Title | Summary |
|---|---|---|
| V2001 | type_mismatch | An expression has a different type from the one its context requires. |
| V2002 | arity_mismatch | A function was called with the wrong number of arguments, or a pattern has the wrong number of fields. |
| V2003 | not_callable | The callee of a call expression is not a function: a value of another type is followed by (…). |
| 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 | infinite_type | Inference would need a type that contains itself (the occurs check failed). |
| V2010 | cannot_infer_type | The type of an empty collection literal (or another binding) cannot be inferred from its uses. |
| V2015 | error_union_annotation_needed | Two different error unions meet in synthesis mode (for example the branches of an if). |
| V2031 | not_show | A value whose type is not Show was interpolated or printed. |
| V2032 | constraint_not_satisfied | A type does not satisfy a constraint the operation requires: Eq, Ord, Hash or Schema (Show is V2031). |
| 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 | 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 | unused_value | A non-final expression statement produces a non-Unit value that is dropped. |
| V2041 | assign_captured_var | A lambda, or a try body, assigns to a var declared outside it. |
| V2050 | hole_in_build | sakura build, sakura run and sakura test reject typed holes (?name). |
Effects and handlers
| Code | Title | Summary |
|---|---|---|
| V3001 | effect_not_allowed | The body performs an effect that the function's signature does not allow. |
| 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 | try_unknown_failures | try without catch must name every failure of its body in Result<T, E>. |
| V3010 | invalid_operation_row | An effect operation's row may contain only Fail<…> in v0 (design §5.5). |
| V3011 | handler_clause_mismatch | A handler must provide exactly one clause per operation of its effect, with matching parameter counts (design §5.5). |
| V3012 | with_non_handler | with was given something that is not a Handler<E, r> value. |
| V3020 | test_unhandled_effect | Tests run under deterministic default handlers for Clock, Random, Env, Console and Log (design §5.8). |
Patterns
| Code | Title | Summary |
|---|---|---|
| V4001 | non_exhaustive_match | A match does not cover every value. |
| V4002 | unreachable_arm | A match arm can never be reached because earlier arms already cover every value it matches. |
| 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
| Code | Title | Summary |
|---|---|---|
| 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 | refinement_checked_at_runtime (retired) | Retired (design §17.87, §12.3): never reported. |
| V5003 | validate_target_not_refined | Untrusted.validate(u) takes its target V from the expected type Result<V, Violation>. |
| 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
| Code | Title | Summary |
|---|---|---|
| V6001 | capability_construction | Capability values (Dir, NetScope, EnvScope, SecretStore) cannot be constructed by user code. |
| V6002 | scoped_value_escape | A scoped value escapes the with that bounds it (design §6.3, §17.70). |
| 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 | 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
| Code | Title | Summary |
|---|---|---|
| V8001 | missing_entry_point | sakura run needs pub fn main() -> Unit ! {…} in the program it runs (design §9). |
| V8002 | reserved_package_name | sakura.toml names its package std or main (design §9, §17.131). |
| 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 | 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 | spec_frozen | A patch modifies a frozen symbol's signature, effect row, error union, contracts, or a test body (design §7.3). |
Internal
| Code | Title | Summary |
|---|---|---|
| V9001 | internal_error | The compiler hit a bug. |
| V9002 | phase_unavailable | A compiler phase needed by this command is not implemented yet in this pre-alpha build. |
Warnings
| Code | Title | Summary |
|---|---|---|
| W1002 | shadowed_import | A local binding shadows an imported name. |
| W4010 | catch_all_on_open_union | A catch uses _ => … on an error union that may grow. |
| 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 | property_discard_budget | A property discarded more than 90% of its generated inputs, so it tested almost nothing (design §7.4, §17.64). |
| 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 | 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
| Code | Title | Summary |
|---|---|---|
| D001 | int_overflow | Checked Int arithmetic overflowed 64 bits. |
| D002 | division_by_zero | / or % was evaluated with a divisor of 0. |
| D003 | int_beyond_js_safe_range | On the JS backend, an Int left the exactly representable range ±(2^53−1). |
| D004 | float_not_finite | Float.round or a float-to-int conversion was given NaN or ±∞. |
| D010 | refinement_violated | A checked introduction such as Email.from(s) received a value that fails the refinement. |
| D011 | contract_evaluation_failed | Evaluating a contract predicate itself defected (for example it overflowed). |
| D020 | precondition_violated | A requires clause failed on entry. |
| D021 | postcondition_violated | An ensures clause failed on normal return. |
| D030 | option_expect_none | Option.expect was called on None. |
| D031 | string_slice_not_char_boundary | String.slice was given a byte offset that is not on a UTF-8 character boundary. |
| 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 | host_failure | A host operation failed outside Sakura Lang's control (for example a rejected host promise). |
| D092 | rc_overflow | On the WASM runtime, an object's reference count would pass 2^32 − 1. |
| D093 | finalizer_failed | On the WASM runtime, a finalizer (the cleanup of Fs.with_file and similar) failed with an error. |
| D094 | context_escaped | On the WASM runtime, an operation callback was called after its handler's perform site was gone. |
| D095 | fiber_retired | On the WASM runtime, join was called on a fiber that had already been retired. |
| D096 | heap_exhausted | On the WASM runtime, the heap limit (SAKURA_MAX_HEAP) was reached or memory could not grow. |