Skip to main content
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.
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:
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.
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).
Symptom. A request returns 403 with body:
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).
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.:
Then pass a supported target to visiq() — see the SDK Reference detection table.
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:
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.
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:
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.
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.

​
Still stuck?

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

A harness key is set

VISIQ_API_KEY is a vq_prod_ / vq_test_ key from Settings → Harness Keys.
2

An endpoint is set

VISIQ_ENDPOINT=https://api.visiqlabs.com (Python also accepts VISIQ_BASE_URL).
3

A stable agent id is set

VISIQ_AGENT_ID=support-bot so the same agent shows up run to run.
4

The model provider key is set

OPENAI_API_KEY (or your chosen provider’s key) so the sample agent can call its model.
With all four set, run the agent once and open the dashboard — the agent appears under Harness → Agents and its decisions stream into Harness → Runtime Enforcement.