Error codes

Every error Nika emits is a typed structure with a stable code, a category, and a transient flag the retry machinery reads. The format is NIKA-<NAMESPACE>-<NNN>. An optional sub-namespace self-documents builtin errors (NIKA-BUILTIN-WAIT-001). The full grammar:

^NIKA-[A-Z]{2,9}(-[A-Z][A-Z0-9_]{1,15})?-[0-9]{3}$

Canonical source: spec/05-errors.md owns the taxonomy: engines derive from it, never the reverse. The machine-readable registry lives in the spec’s canon.yaml and is also served as JSON at nika.sh/errors/catalog.json. The tables below are generated from that registry.

The error shape

{
  "code": "NIKA-INFER-001",
  "category": "provider_error",
  "message": "Anthropic API returned 503 service unavailable",
  "transient": true,
  "details": { "provider": "anthropic", "status_code": 503 },
  "task_id": "research",
  "attempt": 2
}

transient: true means a retry might succeed. retry: only fires on transient errors (unless on_codes: widens it). on_error: catches the final error either way, and on_error.on_codes routes recovery by exact code.

Category	Meaning
`parse_error`	Workflow YAML is malformed or invalid
`validation_error`	Workflow violates a spec rule (cycle · unknown field · …)
`variable_error`	Reference to undefined variable or invalid path
`provider_error`	LLM provider returned an error
`network_error`	Network failure (DNS · TCP · TLS · timeout)
`tool_error`	Builtin or MCP tool returned an error
`process_error`	exec: subprocess failure (non-zero exit · spawn)
`budget_error`	An agent: loop budget exhausted (max_turns · max_tokens_total)
`security_error`	SSRF · blocklist · capability denied
`timeout_error`	Task or step exceeded its timeout
`cancelled`	Workflow or task cancelled
`internal_error`	Engine bug · unexpected state

The registered codes (v0.1 normative floor)

A conformant engine emits exactly these codes for these failures. Engines may add codes within a namespace’s 001-099 range. Never repurpose one.

Code	Failure	Category	`transient`
`NIKA-PARSE-001`	the YAML itself does not parse (syntax error)	`parse_error`	false
`NIKA-PARSE-002`	missing envelope field (nika: / workflow: / non-empty tasks:)	`validation_error`	false
`NIKA-PARSE-003`	nika: version marker is not exactly v1	`parse_error`	false
`NIKA-PARSE-004`	workflow: id violates ^[a-z][a-z0-9-]*$	`validation_error`	false
`NIKA-PARSE-005`	unknown field — strict mode rejects anything outside the closed v1 set	`validation_error`	false
`NIKA-PARSE-006`	task id violates ^[a-z][a-z0-9_]*$ (snake_case · CEL-safe · no hyphens)	`validation_error`	false
`NIKA-PARSE-007`	duplicate task id within the workflow	`validation_error`	false
`NIKA-PARSE-008`	task declares no verb — exactly one of infer/exec/invoke/agent required	`validation_error`	false
`NIKA-PARSE-009`	task declares multiple verbs — exactly one required	`validation_error`	false
`NIKA-PARSE-010`	timeout: violates the quoted Go-duration contract (positive · max 24h · descending units)	`validation_error`	false
`NIKA-PARSE-011`	retry: block violates the spec shape	`validation_error`	false
`NIKA-PARSE-012`	on_error: block violates the spec shape (fields mutually exclusive)	`validation_error`	false
`NIKA-PARSE-013`	with:/output: binding uses a reserved name (output · status · error · started_at · ended_at · duration_ms)	`validation_error`	false
`NIKA-PARSE-014`	secrets: entry is not a store reference — inline literals forbidden	`validation_error`	false
`NIKA-PARSE-017`	duplicate mapping key — no silent last-wins	`validation_error`	false
`NIKA-PARSE-018`	missing required field in a verb body (infer.prompt · exec.command · invoke.tool)	`validation_error`	false
`NIKA-PARSE-019`	generic structural validation — wrong YAML shape for a field	`validation_error`	false
`NIKA-PARSE-020`	workflow: is a scalar — the envelope became an object (workflow: then id: <value>)	`validation_error`	false
`NIKA-PARSE-021`	top-level description: — it moved into workflow.description	`validation_error`	false
`NIKA-PARSE-022`	tasks: is a sequence — it became a map keyed by task id (drop `- id:`, the key IS the identity)	`validation_error`	false
`NIKA-PARSE-023`	a task carries an id: field — the map key is the identity, the field is gone	`validation_error`	false
`NIKA-PARSE-024`	a task carries depends_on: — dead since W2 (data → with: bindings · control → after: predicates · check —fix migrates)	`validation_error`	false
`NIKA-PARSE-025`	decode: with capture: structured — that capture already IS an object · type it with returns:	`validation_error`	false
`NIKA-PARSE-026`	a declared entropy x clock contradiction · entropy: ambient paired with clock: virtual — the ambient declaration contradicts the determinism demand (NEP-0010 · F-P3)	`validation_error`	false
`NIKA-PARSE-027`	a declared entropy x clock contradiction · entropy: none	seeded paired with clock: system — deterministic journals cannot ride the wall clock (NEP-0010 · F-P3)	`validation_error`	false
`NIKA-PARSE-028`	entropy: none declares strict determinism while a structural randomness source is consumed (a live retry jitter · nika:uuid) — the strict declaration cannot hold (NEP-0010 · F-P3 · judged at check)	`validation_error`	false
`NIKA-COMP-001`	invoke.workflow: target is not statically resolvable (templated · malformed · unpinned registry ref) — a call graph you cannot draw before the run cannot be bounded (spec 14)	`validation_error`	false
`NIKA-COMP-002`	the child workflow’s effect boundary exceeds the parent capped by the call-site declaration (Authority(child) subset of Authority(parent) intersect declared · spec 14 laws 3/4)	`security_error`	false
`NIKA-COMP-003`	the static call graph is not acyclic (self-launch · cycle · spec 14 law 7 · NIKA-SEC-003 is the runtime depth backstop)	`validation_error`	false
`NIKA-COMP-004`	the typed call does not compose — parent args do not fit child inputs, or child outputs do not fit parent returns (spec 14 law 2)	`validation_error`	false
`NIKA-DAG-001`	cycle in the precedence graph G_p = E_d ∪ E_c (incl. self-dependency · via with:/after:)	`validation_error`	false
`NIKA-DAG-002`	with:/after: references an undeclared task	`validation_error`	false
`NIKA-DAG-004`	on_error.recover references a task downstream of the declaring task (await would deadlock)	`validation_error`	false
`NIKA-DAG-005`	after: predicate outside the closed set (success · failure · skipped · terminal)	`validation_error`	false
`NIKA-DAG-006`	statically dead task — an incoming edge’s pass-set excludes every reachable producer state, or the when: gate is false under every reachable upstream combination (gate algebra v2)	`validation_error`	false
`NIKA-DAG-007`	status compared against a literal outside the vocabulary (success · failure · skipped · cancelled) — == never matches, != always holds	`validation_error`	false
`NIKA-TYPE-001`	unknown type name (in types: · returns: · an outputs: type) — did-you-mean when close	`validation_error`	false
`NIKA-TYPE-002`	recursive type reference — the types: graph must be acyclic	`validation_error`	false
`NIKA-TYPE-003`	returns: and schema: on the same task — one contract, one spelling	`validation_error`	false
`NIKA-TYPE-004`	returns: type unreachable from the declared decode: (an object contract over decode: text · …)	`validation_error`	false
`NIKA-TYPE-005`	a secret-carrying type in a lowered position (reserved with secret<T> · W4)	`security_error`	false
`NIKA-TYPE-006`	regex pattern outside the locked dialect (backreference · lookaround · named group · inline flags · lazy/possessive · word-boundary · unicode-class — spec 09 §the regex dialect)	`validation_error`	false
`NIKA-TYPE-101`	run-time contract violation — the decoded value does not fit returns: (exec:/invoke: lane)	`validation_error`	false
`NIKA-VAR-001`	unresolved reference (unknown namespace entry · undeclared inputs/config/const/secrets/with key)	`variable_error`	false
`NIKA-VAR-002`	binding cardinality — a jq binding emitted zero or multiple values	`variable_error`	false
`NIKA-VAR-003`	provably-invalid path into a declared schema (static walk)	`validation_error`	false
`NIKA-VAR-004`	jq runtime error while evaluating a binding	`variable_error`	false
`NIKA-VAR-005`	static expression violation — outside cel-subset/0.1 · chained relation · unknown function · non-boolean when: root · jq compile error	`validation_error`	false
`NIKA-VAR-006`	expression type error at evaluation — cross-type compare · non-boolean when: value · for_each over a non-array	`variable_error`	false
`NIKA-VAR-007`	bytes value substituted into a string position	`variable_error`	false
`NIKA-VAR-008`	unclosed ${{ opener	`validation_error`	false
`NIKA-VAR-020`	bare tasks.X is the envelope, not a value — the projection set (.output/.status/.error/.duration_ms) is closed and required (04 §namespaces · 0.103 · #75 D2)	`validation_error`	false
`NIKA-VAR-021`	a tasks.* reference outside the boundary (with: · after: · on_error.recover · on_finally parent-only · workflow outputs) — hoist it into with: (check —fix applies it)	`validation_error`	false
`NIKA-VAR-009`	typed outputs value did not match its declared type: at run end (the output half of the callable contract)	`validation_error`	false
`NIKA-INFER-001`	provider call failed (HTTP error · provider refusal)	`provider_error`	engine-assessed
`NIKA-INFER-002`	structured output failed schema validation (after any engine-internal retries)	`validation_error`	false
`NIKA-INFER-003`	the provider reported no token usage for a priced model — the ledger cannot bill the call honestly (fail-closed · R3-F1)	`validation_error`	false
`NIKA-EXEC-001`	non-zero exit code (default capture modes)	`process_error`	false
`NIKA-EXEC-002`	spawn failure (command not found · permission)	`process_error`	false
`NIKA-INVOKE-001`	unknown tool (unresolvable nika:/mcp: id)	`validation_error`	false
`NIKA-INVOKE-002`	tool args failed the tool’s schema	`validation_error`	false
`NIKA-AGENT-001`	max_turns exhausted before completion	`budget_error`	false
`NIKA-AGENT-002`	max_tokens_total exhausted before completion	`budget_error`	false
`NIKA-AGENT-003`	a skills: path does not resolve (file missing/unreadable at compose time)	`validation_error`	false
`NIKA-AGENT-004`	a skills: file is not a valid Agent Skill (frontmatter shape · missing/empty name/description)	`validation_error`	false
`NIKA-AGENT-005`	the provider reported no token usage for a priced model — every budget and ledger reads the turn as free, so the loop fails closed (R3-F1 · the usage-absence gate)	`budget_error`	false
`NIKA-MCP-001`	MCP server not configured / not reachable at call time	`tool_error`	engine-assessed
`NIKA-MCP-002`	MCP tool call failed (transport · tool-side error)	`tool_error`	engine-assessed
`NIKA-DECIDE-001`	the decision bundle is malformed or violates its own laws (float weight · undeclared evidence key in rules · identity key feeding a technical dimension · missing contradictory fixture · monotonicity violated by the bundle’s own fixtures) (spec 11)	`validation_error`	false
`NIKA-DECIDE-002`	the evidence snapshot does not satisfy the bundle’s evidence schema (type misfit · unauthorized source · integrity below the declared floor · undeclared key) (spec 11)	`validation_error`	false
`NIKA-POLICY-001`	a hard policy: rule is violated (require.human_gate_before · forbid.exec_after · allow.providers · limits.max_tasks) — the diagnostic names rule + task + witness (order rules: the path) · check-time, before any token (spec 10)	`security_error`	false
`NIKA-PORT-001`	a gateway artifact (deployment bundle · capabilities report · lowering report · fidelity report · authority delta) is malformed or violates its laws (unknown promoted · permissive_unsafe without refusal · disclosure subset-chain violated · child authority exceeding parent) (spec 12)	`validation_error`	false
`NIKA-PORT-002`	policy lowering is permissive_unsafe — the backend would allow what the policy forbids · refused with the divergence witness (spec 12)	`security_error`	false
`NIKA-SEC-001`	exec refused before the child spawns — either the shell floor (a destructive/privilege pattern · always-on · independent of permits:) or the mock plane under `nika test`, which refuses EVERY command by design (it simulates the model, not effects) · under test the exit is `nika run` for real effects, or an `on_error: recover` rehearsal on the task	`security_error`	false
`NIKA-SEC-002`	agent tool call outside the tools: whitelist	`security_error`	false
`NIKA-SEC-003`	run-recursion bound — nested-run depth exceeded OR self-launching workflow	`security_error`	false
`NIKA-SEC-004`	effect outside the declared permits: capability boundary (fs/net/exec/tool)	`security_error`	false
`NIKA-SEC-005`	SSRF block — a nika:fetch/nika:notify URL resolves to a loopback/private/link-local/metadata target (always-on engine floor · independent of permits:)	`security_error`	false
`NIKA-SEC-006`	secret flow — a secrets.<name> value reaches an unsanctioned sink (exec argument · invoke payload · infer/agent prompt) · the diagnostic carries the taint path + the egress clause that would sanction it (spec 10 · flow rules in 01 §egress)	`security_error`	false
`NIKA-SEC-007`	secret egress — a tainted value reaches the workflow boundary (outputs:) · the diagnostic carries the taint path (spec 10 · the to: outputs sanction in 01 §egress)	`security_error`	false
`NIKA-SEC-008`	data-as-code sink · a nika:fetch resolved URL path names a code-bearing class (serialized-executable · script/interpreter · executable binary/module · the closed NEP-0006 list) and the task declares no inert: door · the read hides an execution sink (F-O7 · NEP-0006)	`security_error`	false
`NIKA-SEC-009`	lethal trifecta complete — the declared boundary grants private read (fs.read non-empty) + untrusted ingress (a nika:fetch builtin invoked · an mcp:* tool invoked · an agent: whose whitelist admits ingress) + external egress (net.http non-empty · an escaping fs.write glob · exec enabled), the untrusted content REACHES an egress-capable task’s effect surface (a realized flow), and no blocking invoke: nika:prompt (no default:) dominates it (NEP-0002 v2.0 · the Rule of Two as a static check)	`security_error`	false
`NIKA-SEC-010`	the approval-capability law is violated · a rate-limited approval burst (the N+1th distinct mint of a run) · an approval whose resolved content hash differs from the shown hash (content_mismatch) · a ticket replayed across runs or steps (scope_mismatch) · or the static heterogeneous-batch refusal (one prompt unleashing two or more effect classes) — the 6th invariant (NEP-0013 · F-P4)	`security_error`	false
`NIKA-SEC-011`	preview-commit divergence — the commit digest recomputed at the sink over the exact bytes about to fire differs from the preview digest computed at resolution (one bit of rendered argv · a permuted context field · a mutated tool argument) · the step refuses fail-closed and the receipt carries divergence:{preview, commit} — judged = executed at the action scale (NEP-0015 · F-P6)	`security_error`	false
`NIKA-SEC-012`	unordered shared writes — two tasks incomparable in the DAG closure whose literal nika:write/nika:edit paths collide with no ordering edge (after: · with:) to serialize them, or a for_each fan writing one constant path · parallelism is safe exactly where the writes are provably disjoint (NEP-0014 law 1 · F-P15)	`security_error`	false
`NIKA-SEC-013`	the endorsement mode law — a human gate (invoke: nika:prompt) declared under a policy: block that names no endorsement mode refuses fail-closed (endorsement.undeclared_mode · F-F5 · zero implicit escape), and endorsement: solo carried by a workflow with more than one gate refuses as the declaration lying (endorsement.solo_count · exactly one endorser) (NEP-0017 · F-P23)	`security_error`	false
`NIKA-SEC-014`	the affirmative-consent law — a confirm-mode human gate (invoke: nika:prompt · mode absent or confirm) reaches an egress-capable task over a route no affirmative gate closes: a REFUSED confirm settles success with value false, so a bare after: { gate: success } edge, a when: that never reads the answer, and a when: provably true on the refusal all let the effect through · the gate is credited only when every route consumes the answer and proves false on it (the Kleene-falsifiable when: · when: false · a closer confirm gate owns its closure) · an undecidable gate (a nested binding · a non-fragment expression) defers to the advisory hint, never a refusal (NEP-0020 · P0-2 of the 2026-07-30 audit)	`security_error`	false
`NIKA-TIMEOUT-001`	task (or for_each iteration) exceeded timeout:	`timeout_error`	false
`NIKA-CANCEL-001`	task cancelled (workflow failure gate · user cancellation)	`cancelled`	false
`NIKA-ASSERT-001`	an assert: claims a level the evidence does not support (a StaticProof the IR cannot decide · a mis-leveled obligation · spec 15)	`validation_error`	false
`NIKA-LOCK-001`	a dependency resolved that nika.lock does not pin, or a hand-edited lock digest does not match (pin-by-default · the lock’s own hash catches the edit · spec 15)	`validation_error`	false
`NIKA-BUILTIN-001`	builtin invoke violates its statically-checkable arg contract (e.g. nika:fetch without url: · nika:jq arg shape)	`validation_error`	false
`NIKA-BUILTIN-DONE-001`	nika:done invoked outside an agent: loop	`validation_error`	false
`NIKA-DRIFT-001`	declared-but-unused — a vars:/env:/secrets: name or a permits: entry (exec program · tool glob · net host · fs path) that nothing in the body references (advisory check hint · never fails the audit — the reverse direction, used-but-undeclared, is the hard NIKA-VAR-001/NIKA-DAG-002/NIKA-SEC-004 surface)	`validation_error`	false
`NIKA-AUTH-006`	no permits: block declared and the body has effects — absent = zero authority (F-O8 · NEP-0003)	`security_error`	false
`NIKA-AUTH-007`	an interpolation reaches a permit bound (host · glob · program · env name) — a bound MUST be a literal, the boundary would be self-serve (F-O1 · NEP-0004 · env per NEP-0005)	`security_error`	false
`NIKA-AUTH-008`	an untrusted value reaches a permitted verb’s argument and its canonical resolved form escapes the step’s permit — re-gate refused (F-O1 · NEP-0004)	`security_error`	false
`NIKA-AUTH-009`	a permits env: entry names a dangerous-floor variable · the engine strips the name unconditionally, the grant can never take effect: an inert dead grant (F-O4 · NEP-0005)	`security_error`	false
`NIKA-AUTH-010`	a permits net.http: entry carries the . subdomain wildcard · the grant delegates the boundary to the zone operator (every host under the suffix, present and future) — refused: name exact hosts, or the bare when allow-all is genuinely intended (F-P5 · NEP-0008)	`security_error`	false
`NIKA-VALUES-001`	vars: is a dead envelope field (R3a · the E-split)	`validation_error`	false
`NIKA-VALUES-002`	env: is a dead envelope field (R3a · the E-split)	`validation_error`	false
`NIKA-VALUES-003`	a value-namespace read outside the four-authority family (R3a · LAW-SURFACE-0201)	`validation_error`	false
`NIKA-DEFAULT-001`	a declared default (inputs · config) or typed const value does not conform to its declared type (R3b · LAW-TYPE-0211)	`validation_error`	false

Retired codes (never reuse)

Two allocation holes in the table above are deliberate — a retired code is never repurposed:

NIKA-PARSE-016 — the jq-binding-contains-template class folded into NIKA-VAR-005.
NIKA-DAG-003 — « a tasks.X reference with no declared edge » became inexpressible in W2 « the flow »: the with: binding IS the edge (derived, never restated), and a reference outside the boundary is NIKA-VAR-021.

Namespaces

Namespace	Scope	Range
`NIKA-AGENT`	agent: verb errors	001-099
`NIKA-ASSERT`		001-099
`NIKA-AUTH`		001-099
`NIKA-BUILTIN`	Builtin tool errors · per-builtin sub-namespace	001-099
`NIKA-CANCEL`	Task or workflow cancellation	001-099
`NIKA-COMP`		001-099
`NIKA-DAG`	DAG topology · cycles · invalid deps	001-099
`NIKA-DEFAULT`		001-099
`NIKA-EXEC`	exec: verb errors	001-099
`NIKA-IMPL`	Engine internal errors	001-099
`NIKA-INFER`	infer: verb errors	001-099
`NIKA-INVOKE`	invoke: verb errors	001-099
`NIKA-LOCK`		001-099
`NIKA-MCP`	MCP client errors	001-099
`NIKA-DECIDE`		001-099
`NIKA-DRIFT`		001-099
`NIKA-PARSE`	YAML parse + envelope validation	001-099
`NIKA-POLICY`		001-099
`NIKA-PORT`		001-099
`NIKA-PROVIDER`	Provider adapter errors	001-099
`NIKA-SEC`	Security policy violations (SSRF · blocklist)	001-099
`NIKA-TIMEOUT`	Task or step timeouts	001-099
`NIKA-TYPE`		001-099
`NIKA-VAR`	Variable resolution failures	001-099
`NIKA-VALUES`		001-099

Builtin errors use a per-builtin sub-namespace: each builtin owns its own 001-099 (NIKA-BUILTIN-FETCH-001 is the fetch tool’s network/extraction failure). Underscore-named builtins encode naturally: NIKA-BUILTIN-JSON_MERGE_PATCH-001.

Routing on codes

# Retry ONLY on the fetch network error · fixed 30s backoff
retry:
  max_attempts: 5
  backoff_strategy: fixed
  backoff_ms: 30000
  on_codes: [NIKA-BUILTIN-FETCH-001]

# Recover ONLY on timeout · any other code still fails
on_error:
  on_codes: [NIKA-TIMEOUT-001]
  recover: { stale: true, items: [] }

on_error.skip preserves the original error at tasks.X.error: a downstream task can branch on ${{ tasks.X.error.code }} while the status reads skipped.

The full error model

Retry policies, backoff strategies, recovery semantics, and the gate-based failure propagation rules. See spec/05-errors.md.

YAML

CLI & errors

Data catalogs

Workspace

Error codes

The error shape

Categories

The registered codes (v0.1 normative floor)

Retired codes (never reuse)

Namespaces

Routing on codes

The full error model

​The error shape

​Categories

​The registered codes (v0.1 normative floor)

​Retired codes (never reuse)

​Namespaces

​Routing on codes

The full error model

The error shape

Categories

The registered codes (v0.1 normative floor)

Retired codes (never reuse)

Namespaces

Routing on codes