Troubleshooting

“Invalid API key” / 401

By far the most common problem, and it is almost always the same cause.

Warning

You pasted a provider key where the Vulnetix key goes.

Your client’s api_key must be your Vulnetix API key, not sk-proj-…, not sk-ant-…. The provider key lives in the vault; the gateway injects it. If your client is carrying a provider key, it is carrying the wrong credential.

Work through it in order:

  1. Is it a provider key? Look at what your client is actually sending. If it starts with sk-, that is the bug. See your two keys.
  2. Is the variable set in the right shell? An export in your terminal does not reach a GUI application, an IDE, or a launchd/systemd service. This is why vulnetix ai-firewall install shell writes to your shell rc rather than relying on the current session.
  3. Is the org UUID right? unknown organisation means the UUID in the base URL is wrong, malformed, or the organisation is inactive.
  4. Did you rotate the key recently? Key changes propagate within about a minute.

“No provider key configured” / 403 provider_key_missing

You authenticated fine. There is simply no key in the vault for that provider.

vulnetix ai-firewall key set openai --from-env OPENAI_API_KEY

Note this is per-provider. A key for openai does nothing for anthropic.

404 unsupported_api

Your base URL is wrong, and it is nearly always the /v1.

ClientBase URL
OpenAI SDKs, Codex, curl…/{provider}/{orgUuid}/v1
Anthropic SDKs, Claude Code…/anthropic/{orgUuid} — no /v1

The error message names the route to use instead. Also check the provider actually serves the surface you want — only openai serves responses, only anthropic serves messages. See base URLs.

“Model not allowed” / 403 model_not_allowed

You are in allowlist mode and did not realise. The first allow entry you add for a provider flips it: from that moment, only explicitly allowed models pass.

vulnetix ai-firewall get     # see your model entries

See the flip.

My guardrail is not firing

In order of likelihood:

  1. The pattern does not compile. An uncompilable regex is silently skipped — the rule shows as enabled and enforces nothing. This is the big one.

    vulnetix ai-firewall status     # reports guardrail_pattern_invalid

  2. You used a lookahead or a backreference. RE2 supports neither. See the regex reference.

  3. The rule is disabled. vulnetix ai-firewall get.

  4. An earlier rule blocked first. A block short-circuits, so nothing after it runs. Check your priority values.

  5. The traffic is not going through the firewall at all. See below.

My guardrail is firing constantly

See tuning false positives. Usually the pattern is matching on length rather than structure — [0-9]{9} matches half the internet; \bEMP-[0-9]{6}\b does not.

Prompt-injection rules fire a lot by nature, because people legitimately discuss prompt injection. Consider running those at flag permanently.

The model gives strange answers about “[REDACTED]”

Your redaction rule is working. Redaction is silent — the request succeeds and the client is never told.

Either the rule is too broad (narrow the pattern), or the model genuinely needs that data and redaction is the wrong tool (block instead, or exempt the path by narrowing the rule).

Tell your developers you redact. A silent rewrite they do not know about looks like a broken model.

Traffic is not reaching the firewall at all

vulnetix ai-firewall status

Look for bypasses_firewall, and for a client showing points elsewhere.

Then prove it end to end — add a canary rule and confirm you get a 403 rather than an answer. Verify walks through it.

Note Some traffic bypasses by design and you cannot fix it. Cursor’s tab completions and Auto mode never route through BYOK. See Cursor.

Claude Code will not connect

  1. ANTHROPIC_API_KEY must be explicitly empty, not merely unset. A cached Anthropic credential otherwise takes precedence and you will talk to Anthropic directly.
  2. Log out of any previous Anthropic session — /logout inside Claude Code.
  3. Check the base URL has no /v1.
  4. /status inside Claude Code shows the base URL it is actually using. That is the ground truth.

See Claude Code.

Claude Desktop’s model picker is empty

The picker is populated from GET /v1/models. An empty list usually means you are in allowlist mode and have not allowed any Anthropic models, or you denied them all.

curl https://guardrails.vulnetix.com/anthropic/$ORG/v1/models \
  -H "x-api-key: $VULNETIX_API_KEY"

If that returns models and the picker is still empty, the app has cached the failure — fully quit and reopen.

503

The firewall is refusing to guess. Depending on the message: it could not verify your key, could not load your guardrails, or could not reach its database.

It does not forward requests it could not screen. That is the correct behaviour for a firewall, and it is why authentication and policy are always fail-closed. See the error reference.

413 request_too_large

The request body exceeds 8 MiB. Coding agents reading large files hit this. It is a transport limit, not a policy, and it is not configurable.

Requests are slow

The firewall adds a policy check and a regex pass. That is microseconds — it is not your latency.

Check: the provider itself, whether you are streaming (you should be, for long outputs), and — if you use Claude Code — whether a redaction rule is firing inside a cached prefix and destroying your prompt cache, which makes every turn pay full price. Keep redaction rules narrow on agent traffic.

Still stuck

vulnetix ai-firewall status -o json

That is the complete picture of your policy, your keys, and your local wiring, and it is the first thing to include in a support request.