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.
`OWNERSHIP_CONFLICT`	Another worker already owns maintenance for this store namespace.
`SHUTDOWN_TIMEOUT`	A worker operation did not settle within the shutdown bound.
`TARGET_NOT_FOUND`	A wake or Effect recovery declaration named a missing or non-recoverable target.
`TARGET_DUPLICATE`	Two runtime targets or Effect recovery identities collide.
`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.
`WORK_IDEMPOTENCY_CONFLICT`	A Work idempotency tuple was reused with different input.
`WORK_TARGET_MISMATCH`	Work reconnection used a different exported Flow target.
`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.
`EVAL_REACTIVE_DISPATCH_FORBIDDEN`	Eval execution attempted to wake durable reactive work.

Durable Agent Session codes

Public Session failures use dedicated error classes from @use-crux/core / @use-crux/core/session. Generation-model and recovery codes extend CruxRuntimeError.

Code	Meaning
`SESSION_IDENTITY_CONFLICT`	A Session key is already bound to another Agent target.
`SESSION_NOT_FOUND`	No Session exists for the key in this Runtime namespace.
`SESSION_INPUT_INVALID`	Input failed Prompt schema or JSON-safety admission.
`SESSION_UNSUPPORTED`	The Runtime store cannot persist Agent Sessions.
`GENERATION_MODEL_BINDING_MISSING`	No adapter-bound GenerationModel on Session or Agent.
`GENERATION_MODEL_NOT_STATIC`	Selected model is absent from the Runtime program.
`GENERATION_CAPABILITY_MISSING`	Model cannot cover the Agent language requirements.
`SESSION_TURN_RESULT_ARTIFACT_UNAVAILABLE`	Prepared turn result evidence is missing for recovery.

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.

Public custom-effect failures use CruxEffectError from @use-crux/core/effect. EffectOutcomeUnknownError and RollbackError provide additional structured fields for ambiguity and incomplete rollback.

Code	Meaning
`EFFECT_DUPLICATE_ID`	Two effect definitions share one id and version.
`EFFECT_RESOURCE_FAILED`	Resource projection failed before execution.
`EFFECT_CAPTURE_FAILED`	Recovery pre-state capture failed before execution.
`EFFECT_RECOVERY_REQUIRED`	A required-recovery boundary blocked an irreversible effect.
`EFFECT_SCOPE_NOT_FOUND`	A rollback scope ref is invalid or unavailable.
`EFFECT_RECEIPT_NOT_FOUND`	A receipt ref is invalid, unavailable, or belongs to another definition.
`EFFECT_SCOPE_TERMINAL`	New work targeted a boundary that is rolling back or closed.
`EFFECT_OUTCOME_AMBIGUOUS`	An external outcome is unknown or cannot be reconciled safely.
`EFFECT_ROLLBACK_PARTIAL`	A required rollback did not complete.

Execution evidence codes

CruxEvidenceError covers synchronous authoring and inspection failures. Crux Local also returns evidence-specific asynchronous delivery dispositions.

Code	Meaning
`EVIDENCE_INPUT_INVALID`	An evidence input or destination result is structurally invalid.
`EVIDENCE_SUBJECT_REQUIRED`	No explicit or active execution subject exists.
`EVIDENCE_SUBJECT_NOT_FOUND`	The readable destination cannot resolve the subject.
`EVIDENCE_KIND_INVALID`	The evidence kind is invalid or unresolved.
`EVIDENCE_CONCLUSION_INVALID`	The conclusion does not belong to the selected role.
`EVIDENCE_REFERENCE_INVALID`	The subject or source cannot become a canonical graph reference.
`EVIDENCE_SUPERSESSION_INVALID`	The supersession relationship is invalid.
`EVIDENCE_IDEMPOTENCY_CONFLICT`	Content differs from the first accepted evidence identity.
`EVIDENCE_WRITE_QUARANTINED`	A closed Eval cell rejected late evidence authoring.
`EVIDENCE_QUERY_UNAVAILABLE`	No active collector or readable destination can answer.
`EVIDENCE_CURSOR_INVALID`	The cursor is invalid, stale, or bound to another query.
`EVIDENCE_ACCESS_DENIED`	The destination denied evidence inspection.
`EVIDENCE_INPUT_TOO_LARGE`	A bounded Local evidence request exceeded its input limit.
`EVIDENCE_QUERY_FAILED`	Local could not complete the evidence query.
`EVIDENCE_STAGING_CAPACITY`	Durable evidence staging is temporarily full.
`EVIDENCE_STAGING_CANDIDATE_TOO_LARGE`	One evidence payload candidate exceeds the fixed bound.
`EVIDENCE_PRIVACY_DELETED`	Delivery references explicitly deleted private state.

Runtime Errors

Codes

Durable Agent Session codes

Request-scoped defer codes

Effects codes

Execution evidence codes

On this page