> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nika.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting & FAQ

> The errors you'll actually hit, what they mean, and the questions everyone asks — version story, runnable state, providers, syntax dialects.

export const CANON = {
  schemaVersion: 1,
  verbs: 4,
  verbNames: ["infer", "exec", "invoke", "agent"],
  namespaces: 5,
  namespaceNames: ["vars", "with", "tasks", "env", "secrets"],
  builtins: 23,
  builtinNames: ["assert", "compose", "convert", "date", "done", "edit", "emit", "fetch", "glob", "grep", "hash", "inspect", "jq", "json_diff", "json_merge_patch", "log", "notify", "prompt", "read", "uuid", "validate", "wait", "write"],
  providers: 14,
  providersCloud: 8,
  providersLocal: 5,
  providersTest: 1,
  providerIdsCloud: ["mistral", "anthropic", "openai", "gemini", "deepseek", "xai", "groq", "openrouter"],
  providerIdsLocal: ["ollama", "lmstudio", "llamacpp", "localai", "vllm"],
  providerIdsTest: ["mock"],
  extractModes: 9,
  extractModeNames: ["article", "feed", "jq", "links", "markdown", "metadata", "selector", "sitemap", "text"],
  errorNamespaces: 14,
  errorNamespaceNames: ["NIKA-AGENT", "NIKA-BUILTIN", "NIKA-CANCEL", "NIKA-DAG", "NIKA-EXEC", "NIKA-IMPL", "NIKA-INFER", "NIKA-INVOKE", "NIKA-MCP", "NIKA-PARSE", "NIKA-PROVIDER", "NIKA-SEC", "NIKA-TIMEOUT", "NIKA-VAR"],
  errorCategories: 12,
  errorCodes: 50,
  pillars: 5
};

export const STATUS = {
  head: "95962d5cd",
  branch: "main",
  version: "0.91.0",
  cratesWorkspace: 39,
  cratesAdmitted: 39,
  cratesTarget: "42",
  wipCrates: [],
  libTests: 2989,
  clippyWarnings: 0,
  adrs: 62,
  adrsAccepted: 42,
  adrsProposed: 18,
  providers: 32,
  capabilityRules: 49,
  hygieneVectors: 38,
  hygieneGreen: 28,
  hygieneYellow: 3,
  hygieneRed: 0,
  lastUpdated: "2026-06-25"
};

## The questions everyone asks

<AccordionGroup>
  <Accordion title="Can I run Nika today?" icon="play">
    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.
  </Accordion>

  <Accordion title="Why is the language v1 but the engine pre-1.0?" icon="code-branch">
    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.
  </Accordion>

  <Accordion title="Is fetch a verb?" icon="globe">
    No — there are exactly {CANON.verbs} 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.
  </Accordion>

  <Accordion title="Which providers work offline?" icon="server">
    {CANON.providersLocal} 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.
  </Accordion>

  <Accordion title="Do I write {{ }} or ${{ }}?" icon="dollar-sign">
    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`.
  </Accordion>

  <Accordion title="My YAML is valid — why does nika check still fail?" icon="shield-check">
    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.
  </Accordion>
</AccordionGroup>

## Errors you'll hit, decoded

Every failure is a typed structure with a stable code and a `transient`
flag ([error model](/reference/error-codes)). 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](/concepts/security)).     |
| 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

<Steps>
  <Step title="Read the code, not the message">
    `NIKA-<NAMESPACE>-<NNN>` is stable and greppable — the
    [catalog](/reference/error-codes) gives the namespace's contract.
  </Step>

  <Step title="Check transient">
    `transient: true` → retry can help (declare `retry:` with backoff).
    `transient: false` → the input or the file is wrong; retrying burns
    money.
  </Step>

  <Step title="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).
  </Step>

  <Step title="Ask with context">
    [GitHub issues](https://github.com/supernovae-st/nika/issues) with
    the code + the task id + the minimal YAML. Security findings:
    [security@supernovae.studio](mailto:security@supernovae.studio), never public issues.
  </Step>
</Steps>

## See also

<CardGroup cols={2}>
  <Card title="Error codes" icon="triangle-exclamation" href="/reference/error-codes">
    The {CANON.errorNamespaces} namespaces + the typed error shape.
  </Card>

  <Card title="Templates" icon="copy" href="/guides/templates">
    Skeletons that avoid most of these errors by construction.
  </Card>

  <Card title="Security model" icon="shield-halved" href="/concepts/security">
    Why fetch/exec block what they block.
  </Card>

  <Card title="Live engine state" icon="gauge" href="/reference/status">
    What's admitted today ({STATUS.cratesAdmitted}/{STATUS.cratesTarget} crates).
  </Card>
</CardGroup>