Troubleshooting & FAQ

The questions everyone asks

Can I run Nika today?

Yes. Install the latest tagged release with Homebrew or install.sh, then run nika check and nika run locally. The engine is still pre-1.0 and hardening toward the 1.0 launch, but the nika: v1 language envelope is already stable.

Why is the language v1 but the engine pre-1.0?

Two independent axes. The language envelope nika: v1 is frozen forever: files you write never break. The engine follows real semver toward 1.0 (0.90 release-candidate today, then 1.0.0, 1.1, …). Same model as SQL or GraphQL: the contract is stable, implementations iterate.

Is fetch a verb?

No. There are exactly verbs (infer · exec · invoke · agent), locked forever. Fetching a URL is calling a tool: invoke: { tool: "nika:fetch" }. If you see fetch: as a verb anywhere, it’s the pre-spec legacy dialect.

Which providers work offline?

local runtimes (Ollama · LM Studio · llama.cpp · LocalAI · vLLM). Point model: ollama/llama3.2:3b at your machine and the whole workflow runs with zero cloud. mock/echo runs with nothing at all: that’s what the templates default to.

Do I write {{ }} or ${{ }}?

Always ${{ … }}: what’s inside is CEL. The bare {{ … }} form is legacy and rejected by the validator. Same rule: there are no template filters (| upper, | truncate): transforms are jq, in output: bindings or nika:jq.

My YAML is valid, so why does nika check still fail?

Schema-valid ≠ spec-valid. The validator also enforces the semantic rules: tasks.* references live at the boundary only (with: · after: — a body reference is NIKA-VAR-021, hoist it into with:), when: must be a CEL boolean over local namespaces, nika:done only inside an agent’s tool list, exactly one verb per task. The error names the exact rule. Fix that rule, nothing else, re-check.

Errors you’ll hit, decoded

Every failure is a typed structure with a stable code and a transient flag (error model). The frequent ones:

Symptom	Code family	What it means · what to do
« parse error » on a file that looks fine	`NIKA-PARSE`	Usually the envelope: `nika: v1` exactly (not `v1.0` · not `1`), `workflow:` kebab-case, `tasks:` present.
`tasks.X` read refused at check time	`NIKA-VAR-021` · `NIKA-PARSE-024`	A `tasks.*` reference outside the boundary (verb body · `when:` · `for_each:`): hoist it into `with:` — the binding IS the edge (`nika check --fix` applies it). A lingering `depends_on:` is `NIKA-PARSE-024`: data → `with:`, control → `after:`.
`jq`/`fromjson` fails on fetch output (« expecting value, byte 0 »)	`NIKA-BUILTIN-JQ`	The fetch used the default `mode: markdown` (built for pages — it escapes JSON bodies). APIs take `mode: raw`, or `mode: jq` + `jq:` so the shaping rides the fetch.
« unknown binding »	`NIKA-VAR` · `NIKA-VALUES`	Six namespaces only — the four value authorities (`inputs` · `config` · `const` · `secrets`) plus `with` and `tasks`. Typos like `tsaks.` are caught at validation; a read of the dead `vars`/`env` namespaces is `NIKA-VALUES-001`/`-002`, and any other value namespace is `NIKA-VALUES-003`.
« no boundary declared » on a workflow that touches something	`NIKA-AUTH-006`	An absent `permits:` block declares ZERO authority, not a free pass. Run `nika check --infer-permits` — it prints the tightest block the body needs, ready to paste.
provider call fails once then works	`NIKA-PROVIDER` (`transient: true`)	The engine retries with backoff per your `retry:`. Declare it instead of wrapping logic.
fetch refuses a URL	`NIKA-SEC`	SSRF defense: private networks and cloud metadata are blocked by default (security model).
command blocked in exec	`NIKA-SEC-001`	Shell-mode blocklist hit: pass tainted data via `stdin:`/`args:`, never interpolated into `command:`.
agent never finishes	`NIKA-AGENT`	Budgets are mandatory leashes: `max_turns` + `max_tokens_total`, and the loop ends with `nika:done`.

When it breaks, in order

Read the code, not the message

NIKA-<NAMESPACE>-<NNN> is stable and greppable. The catalog gives the namespace’s contract.

Check transient

transient: true → retry can help (declare retry: with backoff). transient: false → the input or the file is wrong; retrying burns money.

Recover structurally

on_error: recover: substitutes a fallback value · on_error: on_codes: scopes recovery to specific codes (recover the not-found, still fail loudly on permission-denied).

Ask with context

Two guided forms exist so nothing gets lost: First run failed (a stumble in your first minutes is a bug, even when nothing crashed) and I was confused here (paper cuts are bugs in the teaching). The output of nika welcome is the perfect diagnostic attachment — it prints key presence, never values. For everything else, Discussions is the fastest lane. Security findings: security@supernovae.studio, never public issues.

Nika ships zero telemetry — the binary never phones home. These forms and Discussions ARE the project’s analytics: a report that you reached your first green run in under two minutes is a data point we cannot get any other way.

Error codes

The namespaces + the typed error shape.

Templates

Skeletons that avoid most of these errors by construction.

Security model

Why fetch/exec block what they block.

Live engine state

What’s admitted today ( crates).

Overview

Getting started

Agents & integrations

Concepts

Troubleshooting & FAQ

The questions everyone asks

Errors you’ll hit, decoded

When it breaks, in order

See also

Error codes

Templates

Security model

Live engine state

​The questions everyone asks

​Errors you’ll hit, decoded

​When it breaks, in order

​See also

Error codes

Templates

Security model

Live engine state

The questions everyone asks

Errors you’ll hit, decoded

When it breaks, in order

See also