Error codes
Each code says what happened and how to fix it. A thrown error stops your code. A failure is a value a function returns, and you decide what to do with it.
thrown stops your code unless you catch itfailure returned as a value for you to handle
135 codes in 12 packages
@arki/async 8 codes
| Code | Kind | What happened |
|---|---|---|
| ARKI_ASYNC_E001 | thrown | A wait is negative, `NaN`, not finite, or above {@link MAX_WAIT_MS}. |
| ARKI_ASYNC_E002 | thrown | Work was cut short by its `AbortSignal` before it finished: a `sleep`, a `scoped` body, or an `all` / `mapConcurrent` / `race` / `timeout` call. |
| ARKI_ASYNC_E003 | thrown | One or more `scoped` finalizers threw. |
| ARKI_ASYNC_E004 | thrown | A `timeout` deadline passed before the task finished. |
| ARKI_ASYNC_E005 | thrown | A `concurrency` limit is not a positive integer or `Infinity`. |
| async.cancelled | failure | Owned execution was cancelled; the external reason stays private. |
| async.deadline | failure | An owned deadline elapsed; work still needs cooperative settlement. |
| async.scope_failed | failure | Multiple owned failures; public counts serialize while original members stay private. |
@arki/cli 6 codes
| Code | Kind | What happened |
|---|---|---|
| cli.cancelled | failure | The run was interrupted by SIGINT or SIGTERM. |
| cli.confirmation_required | failure | The command asks for confirmation and there is no terminal to ask on. |
| cli.input_required | failure | A required value is missing and there is no terminal to ask for it. |
| cli.invalid_input | failure | The command line does not fit the command's input. |
| cli.preview_unsupported | failure | `--dry-run` on a command without `preview`. |
| cli.unknown_command | failure | The command name is not one at this level. |
@arki/clock 4 codes
| Code | Kind | What happened |
|---|---|---|
| ARKI_CLOCK_E001 | thrown | `MockClock.advance` or `advanceAsync` got a negative or non-finite number of milliseconds. |
| ARKI_CLOCK_E002 | thrown | `setTimer` or `sleep` got a delay that is negative, not finite, or longer than a timer can hold. |
| ARKI_CLOCK_E003 | thrown | Legacy abort exception code; sleep now returns SleepCancelled. |
| clock.sleep_cancelled | failure | A sleep ended before its timer because its owner cancelled it. |
@arki/contracts 13 codes
| Code | Kind | What happened |
|---|---|---|
| ARKI_CONTRACTS_E001 | thrown | `defineId` got a non-string prefix. |
| ARKI_CONTRACTS_E002 | thrown | `assertUniqueIdPrefixes` found two prefixes that are equal or start one another. |
| ARKI_CONTRACTS_E003 | thrown | Reserved legacy exception code; ID generation now returns RandomSourceUnavailable. |
| ARKI_CONTRACTS_E004 | thrown | `keyset` got no keys. |
| ARKI_CONTRACTS_E005 | thrown | Reserved legacy exception code; cursor decoding now returns InvalidCursor. |
| ARKI_CONTRACTS_E006 | thrown | A contract key contains `.` or uses a reserved name. |
| ARKI_CONTRACTS_E007 | thrown | `operationOf` got a value that carries no operation. |
| ARKI_CONTRACTS_E008 | thrown | The Drizzle column builder has no runtime config for its schema metadata. |
| ARKI_CONTRACTS_E009 | thrown | `defineId` received a missing, empty or non-string domain kind. |
| ARKI_CONTRACTS_E010 | thrown | `defineId` received an unsupported generation format. |
| contracts.invalid_cursor | failure | A cursor cannot be decoded for this keyset. |
| contracts.invalid_cursor_value | failure | A row has a missing or unrepresentable cursor key. |
| contracts.random_source_unavailable | failure | Secure ID generation has no usable Web Crypto provider. |
@arki/dot 57 codes
| Code | Kind | What happened |
|---|---|---|
| ARKI_DOT_E001 | thrown | A `configure` hook attempted async work (returned a Promise). |
| ARKI_DOT_E002 | thrown | A `configure` hook threw. |
| ARKI_DOT_E003 | thrown | A `boot` hook threw. |
| ARKI_DOT_E004 | thrown | A `start` hook threw. |
| ARKI_DOT_E005 | thrown | One or more `stop` hooks threw — aggregate. |
| ARKI_DOT_E006 | thrown | One or more `dispose` hooks threw — aggregate. |
| ARKI_DOT_E007 | thrown | Caller tried to reuse the app after dispose. |
| ARKI_DOT_E008 | thrown | Caller tried to reuse the app after a failed lifecycle. |
| ARKI_DOT_E011 | thrown | Plugin registered twice. |
| ARKI_DOT_E012 | thrown | A plugin's `needs` entry has no provider among earlier-booted plugins. |
| ARKI_DOT_E013 | thrown | A plugin published a wire key that an earlier plugin already provides. |
| ARKI_DOT_E014 | thrown | A needs alias, publish key, or rename target uses the reserved `$` prefix. |
| ARKI_DOT_E015 | thrown | A lifecycle hook exceeded the app's `hookTimeoutMs` watchdog. |
| ARKI_DOT_E016 | thrown | Two actions in the same binding use the same id. |
| ARKI_DOT_E017 | thrown | Action metadata is not JSON-round-trip safe. |
| ARKI_DOT_E018 | thrown | More than one plugin fills the logging slot. |
| ARKI_DOT_E019 | thrown | Static capability needs form a ring: a feature's need comes back around to itself. |
| ARKI_DOT_E020 | thrown | A feature needs a capability whose (static) provider is mounted after it. |
| ARKI_DOT_E021 | thrown | `$describeAction` named an action the calling plugin may not amend (unknown id, or not its own). |
| ARKI_DOT_E022 | thrown | Two routers of a feature use the same key. |
| ARKI_DOT_E023 | thrown | Two repos of a feature use the same key. |
| ARKI_DOT_E024 | thrown | Two slices of a feature use the same key. |
| ARKI_DOT_E025 | thrown | A feature was declared with no slices. |
| ARKI_DOT_E026 | thrown | A handle the feature needs is missing from the services bag. |
| ARKI_DOT_E027 | thrown | A need alias, infra key, provided key or entrypoint key collides with another slot or a reserved name. |
| ARKI_DOT_E028 | thrown | `override()` named a key that no infra plugin of the feature provides. |
| ARKI_DOT_E029 | thrown | `routerFor()`: an app-contract key is implemented by zero or several features. |
| ARKI_DOT_E030 | thrown | `routerFor()`: a feature's contract is not mounted in the app contract. |
| ARKI_DOT_E031 | thrown | `rpc()`: a procedure's contract `meta` is not plain JSON, so `dot explain` cannot show it. |
| DOT_LOG_E001 | thrown | `boot` ran before the kernel activated the logging slot. |
| dot.action_approval_required | failure | Approval must be verified for this invocation, not inferred from another exposure. |
| dot.action_not_exposed | failure | An adapter may call only an explicitly exposed boundary. |
| dot.action_principal_required | failure | The adapter must authenticate its caller before invoking this action. |
| dot.app_import_failed | failure | Importing the app file threw, or its exported factory did. |
| dot.app_invalid_export | failure | The app file loaded, but no export is a DOT app, or several are and none is `default` or `app`. |
| dot.app_lifecycle_failed | failure | `configure` threw while the CLI prepared the app. |
| dot.app_not_found | failure | No app file at the default paths and no `--app`. |
| dot.dev_already_running | failure | Another `dot dev` is alive in this project: its pid is in the state file. |
| dot.dev_app_started | failure | The app export is already configured, booted or started: `dot dev` cannot own its lifecycle. |
| dot.dev_db_unreachable | failure | `dot dev` found no Postgres to talk to: no URL, a bad URL, or a closed port it could not start. |
| dot.dev_port_in_use | failure | Something already listens on the app port, so the runner would not get it. |
| dot.dev_preflight_failed | failure | The preflight process did not report a result: a crash, a hang past the timeout, or output that is not its report. |
| dot.dev_remote_db_refused | failure | The database is neither on this machine nor a compose service: `dot dev` would migrate it on boot. |
| dot.dev_runner_failed | failure | The app runner (`vite dev`, `--run`, or `dot _serve`) could not be started. |
| dot.doctor_failed | failure | `doctor` found error-severity issues. |
| dot.lazy_closed | failure | An operation tried to initialize a service after its owner closed admission. |
| dot.observability_no_sdk | failure | `doctor --observability` found no OpenTelemetry SDK. |
| dot.preflight_failed | failure | A managed preflight reported a lifecycle failure, retaining the complete report. |
| dot.projection_conflict | failure | Two plugins register different modules for one projection format. |
| dot.projection_execution_failed | failure | `project(manifest)` threw or returned output that does not survive a JSON round trip. |
| dot.projection_import_failed | failure | The projection module could not be resolved or imported, or exports no `project(manifest)`. |
| dot.projection_not_found | failure | No plugin registers the `--as` format. |
| dot.runtime_release_failed | failure | Previous ownership could not be released, so starting another app is unsafe. |
| dot.runtime_replaced | failure | A replaced module no longer owns the application's runtime. |
| dot.target_not_empty | failure | `dot new` would overwrite files in a non-empty target directory. |
| dot.template_missing | failure | The package's bundled template directory is empty or missing. |
| dot.write_failed | failure | `dot new` could not write some files. |
@arki/env 1 code
| Code | Kind | What happened |
|---|---|---|
| ARKI_ENV_PLUGIN_E001 | thrown | The env failed its schema at boot. |
@arki/failure 13 codes
| Code | Kind | What happened |
|---|---|---|
| ARKI_FAILURE_E001 | thrown | `defineFailure` got an empty code, or the reserved code `ok`. |
| ARKI_FAILURE_E002 | thrown | `defineFailure` got a status that is not an integer from 400 to 599. |
| ARKI_FAILURE_E003 | thrown | `match` met a failure code it has no handler for. |
| ARKI_FAILURE_E004 | thrown | `unreachable` was reached, so a value the types said could not happen did happen (often bad data from outside). |
| ARKI_FAILURE_E005 | thrown | Two definitions with the same code were given where codes must be unique. |
| ARKI_FAILURE_E006 | thrown | |
| ARKI_FAILURE_E007 | thrown | |
| ARKI_FAILURE_E008 | thrown | An `invariant` condition was falsy, so code relied on something that is not true. |
| failure.invalid_envelope | failure | An external envelope cannot be trusted as a known failure. |
| failure.unexpected_defect | failure | A caught operation defect, distinct from the UnexpectedFailure exception bridge. |
| schema.async_required | failure | A synchronous operation received an asynchronous validator result. |
| schema.invalid_input | failure | Input failed the schema's checks. |
| schema.validator_defect | failure | A validator threw, rejected, or violated the Standard Schema result contract. |
@arki/log 5 codes
| Code | Kind | What happened |
|---|---|---|
| ARKI_LOG_E001 | thrown | `configure()` ran a second time on the same logging instance. |
| ARKI_LOG_E002 | thrown | A category rule or `to()` names a channel that `configure({ channels })` does not define. |
| ARKI_LOG_E003 | thrown | A level is neither one of the six names nor a severity number from 1 to 24. |
| ARKI_LOG_E004 | thrown | `fakeLog()` ran while another fake was active, or `configure()` ran while a fake owns the instance. |
| ARKI_LOG_E005 | thrown | `reconfigure()` was called on a handle that no longer owns the configuration. |
@arki/math 11 codes
| Code | Kind | What happened |
|---|---|---|
| ARKI_MATH_E001 | thrown | A string is not a number in the accepted syntax. |
| ARKI_MATH_E002 | thrown | An argument is outside what the function accepts. |
| ARKI_MATH_E003 | thrown | Division by zero, or zero raised to a negative power. |
| ARKI_MATH_E004 | thrown | The exact result needs rounding and no rounding mode was given. |
| ARKI_MATH_E005 | thrown | A value cannot be represented in the target type. |
| ARKI_MATH_E006 | thrown | A statistic was asked of an empty or too small data set. |
| ARKI_MATH_E007 | thrown | An input or result exceeds the documented digit limits. |
| ARKI_MATH_E008 | thrown | The runtime lacks an `Intl` feature this call depends on. |
| ARKI_MATH_E009 | thrown | A matrix is singular to working precision. |
| ARKI_MATH_E010 | thrown | An iterative method did not reach its tolerance. |
| ARKI_MATH_E011 | thrown | A matrix that must be symmetric positive definite is not. |
@arki/resilience 7 codes
| Code | Kind | What happened |
|---|---|---|
| ARKI_RESILIENCE_E001 | thrown | The circuit breaker is open and rejected the call. |
| ARKI_RESILIENCE_E002 | thrown | A timeout policy reached its deadline. |
| ARKI_RESILIENCE_E003 | thrown | The caller's own signal aborted the call. |
| ARKI_RESILIENCE_E004 | thrown | A bulkhead had no free execution or queue slot. |
| ARKI_RESILIENCE_E005 | thrown | Every retry attempt failed. |
| ARKI_RESILIENCE_E006 | thrown | A `backoff` builder got an option or an attempt number it cannot use. |
| ARKI_RESILIENCE_PLUGIN_E001 | thrown | `for` or `run` got a name that is not in the presets (only reachable from untyped JS). |
@arki/schema 3 codes
| Code | Kind | What happened |
|---|---|---|
| ARKI_SCHEMA_E003 | thrown | A `withJsonSchema` converter was asked for a target other than draft-2020-12. |
| ARKI_SCHEMA_E004 | thrown | `assert` or `ensure` got a value the schema rejects. |
| ARKI_SCHEMA_E005 | thrown | `is`, `assert` or `ensure` got a schema that validates asynchronously. |
@arki/string 7 codes
| Code | Kind | What happened |
|---|---|---|
| ARKI_STRING_E001 | thrown | An argument is outside what the function accepts (empty needle, negative length, bad glyph). |
| ARKI_STRING_E002 | thrown | Text or bytes are not valid UTF-8: an unpaired surrogate, an overlong form, a bad lead byte. |
| ARKI_STRING_E003 | thrown | An input is not valid strict base64: whitespace, a mixed alphabet, bad padding or an impossible length. |
| ARKI_STRING_E004 | thrown | An `interpolate` template has a malformed placeholder. |
| ARKI_STRING_E005 | thrown | An `interpolate` placeholder has no value and `missing` is `'throw'`. |
| string.invalid_base64 | failure | Noncanonical base64. |
| string.invalid_utf8 | failure | Invalid UTF-8. |