Errors

Every error OKE produces — permanent OKE codes with fixes, gate denials, and subsystem errors, with what to do about each.

OKE has two error families, and confusing them is the most common mistake: failures are values a flow returns ({ data: null, error: { code, data } } — clients switch on error.code), while framework errors are thrown for invariant violations and carry a permanent numeric code, a cause, and a fix.

OKE1101  domain table not found — migrations have not been applied.
         → run `oke db migrate` against this environment.
         https://oke.omqkhafi.dev/e/1101

Codes are permanent once published — you can match on them safely across upgrades.

OKE numeric codes

Code	Name	Cause	Fix
`1001`	undeclared read	Flow reads a resource not in `effects.reads`	Add it to the flow's `effects.reads`
`1002`	undeclared write	Flow writes a resource not in `effects.writes`	Add it to the flow's `effects.writes`
`1003`	undeclared emit	Flow emits a signal not in `effects.emits`	Add it to the flow's `effects.emits`
`1004`	undeclared send	Flow sends a template not in `effects.sends`	Add it to the flow's `effects.sends`
`1005`	undeclared ask	Flow asks a prompt not in `effects.asks`	Add it to the flow's `effects.asks`
`1006`	undeclared secret	Flow reads a secret not in `effects.secrets`	Add it to the flow's `effects.secrets`
`1007`	undeclared call	Flow calls a flow not in `effects.calls`	Add it to the flow's `effects.calls`
`1042`	orphan emit	Emitted signal has no subscriber	Add `on(signal, …)` or declare `optional: true`
`1101`	schema missing	Domain table absent in docker/prod — no auto-DDL	Run `oke db migrate` against this environment

Effects are usually inferred

The 1001–1007 family exists for flows that declare effects explicitly. Most apps never write an effects block — inference covers them — so seeing one of these means an explicit declaration drifted from the code.

Gate denials (typed failures)

Returned, not thrown — the request never reached do:

Code	When	Payload
`Unauthorized`	Policy denied, request not authenticated	—
`Forbidden`	Policy denied, authenticated but not allowed	`gate`, `reason`
`RateLimited`	Rate gate budget exhausted	`retryAfterMs`

Framework validation failures

Code	When
`ValidationError`	Input failed the `in` schema, or a list param isn't whitelisted (`unknown list param "x"`)
`NotFound`	A `store.resource` get/update/remove hit a missing row

Subsystem errors

Thrown by specific subsystems — each names its own cause:

Error	Thrown when	What to do
`VaultBootError`	A vault contract has no value in any resolution layer	Set the missing names — the error lists every gap
`OpenBaoUnavailableError`	Vault driver can't reach OpenBao, or it's sealed, in docker/prod	Restore the vault or unseal it — never silently skipped
`OpenBaoBootstrapError`	First-boot init/unseal failed, or key material is missing/unsafe	Read the message — it names the exact failing step
`AiPiiBuildError`	Build: a flow sends PII fields to a third-party model	Drop the fields or add `allowPii: true` — fields named
`AiSchemaValidationError`	A model response failed the prompt's `out` schema	Fix the prompt or the schema — response didn't conform
`ScheduleNotOverridableError`	Console tried to edit a clock declared without `overridable: true`	Declare it overridable and redeploy
`ClockResourceNotFoundError`	Console action targeted an unknown clock name	Check the name against your `clock()` declarations
`DryRunWriteIsolationError`	A write attempted inside a dry run	Dry runs never write — use a real run
`ManifestValidationError`	The compiled Manifest failed schema validation	Re-run the build; the error names the offending entry
`CrossPlaneError`	A user-plane token was used on the operator plane (or vice versa)	Use the correct principal for the plane
`AttenuationError`	A token was used beyond its attenuated scope	Re-issue with the needed scope
`SessionError`	Session token invalid, expired, or malformed	Re-authenticate
`OperatorError`	Operator-plane operation failed its checks	Error message names the failed check
`AccessGrantError`	Console access grant rejected	Re-request access with a valid grant
`UnsupportedPathError`	A route path shape the router can't compile	Simplify the path pattern

Learn more

Flow — fx.fail and the response envelope
Gate — where the three denials come from
CLI Reference — oke db migrate and friends

OKE numeric codes

Gate denials (typed failures)

Framework validation failures

Subsystem errors

Learn more

On this page