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

# Troubleshooting

> Symptom → cause → fix for the errors you are most likely to hit wiring up the VisIQ harness — bad keys, 401/403 responses, missing peer deps, and a silently ungoverned agent.

Most first-run problems come down to one of a few things: a missing or
wrong-audience key, an unset endpoint, an uninstalled peer dependency, or a
missing `OPENAI_API_KEY` for the sample agent. Find your symptom below.

<AccordionGroup>
  <Accordion title="401 — Invalid API key or token" icon="key">
    **Symptom.** The harness (or a `curl`) gets `401` with body
    `{"error":"Invalid API key or token"}`.

    **Cause.** `VISIQ_API_KEY` is unset, empty, mistyped, or revoked — or you pasted
    something that is not a VisIQ key (a harness key starts with `vq_prod_` or
    `vq_test_`).

    **Fix.** Mint a fresh **harness key** in the dashboard under **Settings →
    Harness Keys**, then set it exactly:

    ```bash theme={null}
    VISIQ_API_KEY=vq_prod_...
    ```

    Keys are shown once at creation — if you lost it, roll a new one. Confirm there
    is no trailing space or newline in your `.env`.
  </Accordion>

  <Accordion title="401 — Unauthorized" icon="lock">
    **Symptom.** A management call (rules, agents, audit log, settings) returns
    `401` with body `{"error":"Unauthorized"}`.

    **Cause.** No credential reached the route, or the session/token could not be
    resolved to a tenant. This is the session/RBAC gate, distinct from the
    key-validation `Invalid API key or token` above.

    **Fix.** For the SDK path you never call management routes directly — the
    harness only uses its operational endpoints, so this points at a hand-rolled
    request. Send a valid credential, and remember that harness keys cannot reach
    management routes at all (see the next item).
  </Accordion>

  <Accordion title="403 — harness_key_not_permitted" icon="ban">
    **Symptom.** A request returns `403` with body:

    ```json theme={null}
    {
      "error": "harness_key_not_permitted",
      "detail": "This is a harness/agent API key. It is limited to the SDK operational routes and cannot access the management API. Use a management API key for this operation.",
      "method": "GET",
      "path": "/rules"
    }
    ```

    **Cause.** You used a **harness key** (`vq_prod_` / `vq_test_`) on a
    **management** route (rules, agents, audit log, settings). Harness keys are
    deliberately confined to the SDK's runtime endpoints — they cannot read or
    write configuration.

    **Fix.** Use a management API key for management calls, and reserve the harness
    key for `VISIQ_API_KEY` in your agent. Management keys are minted separately;
    until self-serve creation ships, drive those workflows from the dashboard (see
    [Platform Automation](/automation/introduction)).
  </Accordion>

  <Accordion title="Cannot find module … / Cannot detect agentic framework" icon="cube">
    **Symptom.** A `Cannot find module 'langchain/agents'` (or similar) at import,
    or the harness throws
    `[VisIQ] Cannot detect agentic framework. Pass a LangChain AgentExecutor, …`.

    **Cause.** The framework peer dependency is not installed, or it is the wrong
    major version. `@visiq/harness` does not bundle any framework — you install the
    one you use. LangChain in particular must be pinned: the sample uses
    `langchain@^0.3` and `zod@^3` (LangChain 1.x moved `AgentExecutor`, and zod v4
    schemas serialize in a way OpenAI rejects).

    **Fix.** Install exactly the packages in your framework tab's install line, e.g.:

    ```bash theme={null}
    npm install @visiq/harness "langchain@^0.3" "@langchain/openai@^0.3" "@langchain/core@^0.3" "zod@^3"
    ```

    Then pass a supported target to `visiq()` — see the
    [SDK Reference](/reference#framework-detection) detection table.
  </Accordion>

  <Accordion title="OpenAI API key is missing / 401 from OpenAI" icon="robot">
    **Symptom.** The agent fails before any VisIQ decision with an OpenAI error
    about a missing or invalid API key.

    **Cause.** The quickstart's sample agents instantiate an OpenAI model
    (`gpt-4o`), which needs `OPENAI_API_KEY`. This is unrelated to your VisIQ key.

    **Fix.** Export it alongside `VISIQ_API_KEY`:

    ```bash theme={null}
    OPENAI_API_KEY=sk-...
    ```

    Any model provider works — swap the model import (e.g. `@ai-sdk/anthropic`) and
    set that provider's key instead. VisIQ governs the tool calls regardless of
    which model drives them.
  </Accordion>

  <Accordion title="Nothing is governed — VISIQ_API_KEY unset" icon="triangle-exclamation">
    **Symptom.** Your agent runs, but no decisions show up and nothing is ever
    blocked — or, in Python, every tool call raises `ToolBlocked`.

    **Cause.** The harness never reached a backend, so it never loaded a rule
    bundle. The endpoint **defaults** to the managed SaaS host
    `https://api.visiqlabs.com`, so the usual cause is a **missing `VISIQ_API_KEY`**
    (with no key there's no backend to reach). The two SDKs then behave differently:

    * **TypeScript** cold-starts in `monitor` (monitor-until-confirmed): every call
      is observed but **nothing is blocked** — you get a silently ungoverned agent.
    * **Python** (`Governor`) **fails closed**: with no bundle, `gate_tool` raises
      `ToolBlocked("Governance unavailable — tool blocked (fail-closed, G001)")`
      and `gate_documents` returns `[]`.

    **Fix.** Set a `VISIQ_API_KEY` — with it, the harness reaches SaaS and loads a
    bundle automatically:

    ```bash theme={null}
    VISIQ_API_KEY=vq_prod_...
    ```

    For **onprem / self-hosted** deployments also set `VISIQ_ENDPOINT`
    (`https://api.visiqlabs.com` is not used there) — Python also accepts the
    `VISIQ_BASE_URL` alias. Governance only takes effect once the harness reaches a
    backend and loads a bundle.
  </Accordion>

  <Accordion title="My agent didn't appear under Harness → Agents" icon="magnifying-glass">
    **Symptom.** You ran the agent but it is not listed on the **Harness → Agents**
    page.

    **Cause.** One of: the harness never reached the backend (missing
    `VISIQ_API_KEY` — or, onprem, an unreachable `VISIQ_ENDPOINT`); the run made no governed tool call yet, so
    there was nothing to report; or it registered under an **auto-derived** id (your
    `package.json` name, then hostname) that you didn't recognize.

    **Fix.** Set all three of `VISIQ_API_KEY`, `VISIQ_ENDPOINT`, and an explicit
    `VISIQ_AGENT_ID`, then run the agent once with a prompt that triggers a tool
    call. The id you set is exactly what appears in the list — auto-provisioned in
    **Monitor — Log only** mode on first contact.
  </Accordion>
</AccordionGroup>

## Still stuck?

Confirm the four things every wired-up agent needs, in order:

<Steps>
  <Step title="A harness key is set">
    `VISIQ_API_KEY` is a `vq_prod_` / `vq_test_` key from **Settings → Harness Keys**.
  </Step>

  <Step title="An endpoint is set">
    `VISIQ_ENDPOINT=https://api.visiqlabs.com` (Python also accepts `VISIQ_BASE_URL`).
  </Step>

  <Step title="A stable agent id is set">
    `VISIQ_AGENT_ID=support-bot` so the same agent shows up run to run.
  </Step>

  <Step title="The model provider key is set">
    `OPENAI_API_KEY` (or your chosen provider's key) so the sample agent can call its model.
  </Step>
</Steps>

With all four set, run the agent once and open the
[dashboard](https://app.visiqlabs.com) — the agent appears under **Harness →
Agents** and its decisions stream into **Harness → Runtime Enforcement**.