The questions everyone asks
Can I run Nika today?
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?
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?
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?
Which providers work offline?
local runtimes (Ollama · LM Studio · llama.cpp
· LocalAI · vLLM). Point
model: ollama/llama3.1 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 ${{ }}?
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 — why does nika check still fail?
My YAML is valid — why does nika check still fail?
Schema-valid ≠ spec-valid. The validator also enforces the semantic
rules: every
${{ tasks.X }} reference needs depends_on: [X],
when: must be a CEL boolean, 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 atransient
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. |
| task referenced but never ran | NIKA-DAG | A ${{ tasks.X }} without depends_on: [X] — every data edge must be a graph edge. |
| « unknown binding » | NIKA-VAR | Five namespaces only (vars · with · tasks · env · secrets) — typos like tsaks. are caught at validation. |
| 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
GitHub issues with
the code + the task id + the minimal YAML. Security findings:
security@supernovae.studio, never public issues.
See also
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).