Runtime Errors

Runtime Engine public failures use CruxRuntimeError. Every error has a stable code, a user-facing explanation, what still works, and an exact next step.

import { CruxRuntimeError } from "@use-crux/core/runtime";

try {
  await flow.waitFor(event);
} catch (error) {
  if (error instanceof CruxRuntimeError) {
    console.error(error.code, error.nextStep);
  }
}

Codes

Code	Meaning
`RUNTIME_REQUIRED`	A runtime-bound API was called without `config({ runtime })`.
`CAPABILITY_MISSING`	The configured stack cannot support a used runtime feature.
`TARGET_NOT_FOUND`	A wake named a target missing from the runtime entry.
`TARGET_DUPLICATE`	Two runtime targets share one durable name.
`TARGET_NOT_EXPORTED`	A discovered target cannot be imported as a named export.
`REPLAY_DIVERGED`	Flow replay no longer matches the suspended snapshot fingerprint.
`ARTIFACTS_STALE`	Generated runtime artifacts are stale.
`WAKE_UNVERIFIED`	HTTP wake verification failed before durable state was touched.
`PUBLIC_URL_UNRESOLVED`	Production HTTP wake has no stable public URL.
`SETUP_REQUIRED`	Required adapter resources are missing or mismatched.
`PAYLOAD_NOT_JSON`	A durable runtime payload is not JSON-compatible.
`WORK_DEAD_LETTERED`	Work exhausted retries and is terminal until operator retry.
`LEASE_LOST`	A stale worker tried to commit after losing its lease.
`NAMESPACE_AMBIGUOUS`	The inferred runtime namespace is unsafe or ambiguous.
`RUNTIME_HOST_ONLY`	A host-bound runtime was used outside its host boundary.

Request-scoped defer codes

Public defer() failures use CruxDeferError from @use-crux/core.

Code	Meaning
`DEFER_SCOPE_REQUIRED`	No active execution scope or ambient host binding.
`DEFER_CAPABILITY_MISSING`	Active scope cannot honor this overload.
`DEFER_SCOPE_SEALED`	Registration after the invocation sealed.
`DEFER_LIMIT_EXCEEDED`	Host callback/nesting bounds exceeded.
`DEFER_REPLAY_UNSAFE`	Public `defer()` inside replayable flow execution.
`DEFER_TARGET_INPUT_REQUIRED`	Named target missing required JSON input.
`DEFER_COMMIT_FAILED`	Named work could not commit before the response.

Runtime Errors

Codes

Request-scoped defer codes

On this page