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 28 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-015`	typed vars: declaration malformed (type in string/number/integer/boolean/array/object)	`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-DAG-001`	cycle in depends_on (incl. self-dependency)	`validation_error`	false
`NIKA-DAG-002`	depends_on references an undeclared task	`validation_error`	false
`NIKA-DAG-003`	a tasks.X reference with no declared edge	`validation_error`	false
`NIKA-DAG-004`	on_error.recover references a task downstream of the declaring task (await would deadlock)	`validation_error`	false
`NIKA-VAR-001`	unresolved reference (unknown namespace entry · undeclared env/vars 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-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-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-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-SEC-001`	exec: blocklist hit	`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-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-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

Namespaces

Namespace	Scope	Range
`NIKA-AGENT`	agent: verb errors	001-099
`NIKA-BUILTIN`	Builtin tool errors · per-builtin sub-namespace	001-099
`NIKA-CANCEL`	Task or workflow cancellation	001-099
`NIKA-DAG`	DAG topology · cycles · invalid deps	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-MCP`	MCP client errors	001-099
`NIKA-PARSE`	YAML parse + envelope validation	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-VAR`	Variable resolution failures	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 — spec/05-errors.md.

​The error shape

​Categories

​The 28 registered codes (v0.1 normative floor)

​Namespaces

​Routing on codes

The full error model

The error shape

Categories

The 28 registered codes (v0.1 normative floor)

Namespaces

Routing on codes