Troubleshooting

If something isn’t working, the fastest diagnostic is always:

/prism:status

It prints your API key prefix, config scope, gateway mode, endpoints, and whether OTEL vars are correctly set. Most issues surface there.

For deeper inspection, tail the debug log:

tail -f ~/.claude/plugins/data/prism-inline/debug.log

Or start a session with debug logging on:

PRISM_DEBUG=1 claude

`/prism:help` returns “unknown command”

The plugin isn’t loaded.

Confirm it’s installed: look for prism@optra-prism in /plugin → Installed.
Restart Claude Code.

If still missing, reinstall:

/plugin marketplace add grumatic/optra-prism-plugin
/plugin install prism

and restart.

Also confirm Node.js 18+ is on your PATH — the hook scripts need native fetch.

”No API key configured” or “Invalid API key format”

The session-start hook prints one of these when it can’t find a valid gck_* key.

Run /prism:setup gck_YOUR_KEY.
Confirm with /prism:status — it should show a gck_abc12… prefix.
If you have one, check that the key is still active on the Gateway Keys page.

No telemetry in the dashboard

Walk this list in order:

Run /prism:status. If it shows Scope: none, OTEL env vars aren’t installed yet — re-run /prism:setup gck_YOUR_KEY and restart Claude Code.
Did you restart Claude Code after setup? OTEL env vars are read at process launch, so a session that was already running won’t pick them up.
Check /prism:status for an endpoints warning. If the ingest URL looks wrong, delete ~/.prism/config-cache.json to force a re-fetch and restart the session.
Give it a few minutes. There’s a short delay between a turn ending and the dashboard surfacing it.
Network reachability. From your shell: curl -sSI https://ingest.prism.optra-ai.com/health. If that fails, your environment is blocking outbound traffic to Prism.

`/prism:status` reports “Scope: both”

OTEL vars exist in both ~/.claude/settings.json and .claude/settings.local.json. They’ll merge silently, but it means two scopes are competing and only one will win depending on where you open Claude Code.

Run /prism:setup again — the command prompts you to pick one scope and removes the other.

Warning: “OTEL vars found in `.claude/settings.json` (shared)”

The plugin never writes OTEL vars to the shared, checked-in .claude/settings.json because the OTLP header embeds your gck_* key. If /prism:status surfaces this warning, it means the vars ended up there manually — likely copied from another settings file — and may have been committed to git.

Remove the OTEL_* entries from the project’s shared .claude/settings.json.
If the file has been committed, rotate your gck_* key on the Gateway Keys page.
Re-run /prism:setup to reinstall the vars at the correct scope (user or project).

See Installation Scopes for the full rules.

Status line not appearing above prompts

The [Prism] status line (response time, tokens, cost, turn) is built by the Stop hook and displayed by the next UserPromptSubmit. If it’s missing:

First turn? There’s no prior turn to summarize yet — the line appears from turn 2 onward.
Is it turned off? Run /prism:status and check the Status line row. Say “toggle status line” to flip it back on (restart required).
Hook crashed? Tail the debug log — search for stop-handler errors.

Gateway routing looks on, but requests still bypass it

/prism:status reports gateway enabled, but responses feel identical to direct mode.

Restart Claude Code. ANTHROPIC_BASE_URL is set at process launch; a running session won’t pick it up.
After restart, verify /prism:status still shows gateway on and a non-empty gateway URL.
Check for other tools that override ANTHROPIC_BASE_URL — some wrappers set it to point at their own proxy. Look at echo $ANTHROPIC_BASE_URL from the terminal Claude Code was launched from.

Calls fail in gateway mode when Claude Code uses an Anthropic API key

If your Claude Code is signed in with ANTHROPIC_API_KEY (rather than a Max/Pro subscription) and gateway mode is on, requests can fail at the gateway because there’s nothing upstream to forward them with.

The gck_* you pass to /prism:setup is an Optra key — it does not replace your Anthropic credential. In gateway mode, Claude Code’s x-api-key: <ANTHROPIC_API_KEY> reaches the Optra gateway, and the gateway needs an upstream Anthropic credential configured for your workspace to forward the call.

If you haven’t set one up yet, switch to Direct mode:

Run /prism:status, say “toggle gateway”.
Restart Claude Code.

Calls then go straight to Anthropic with your ANTHROPIC_API_KEY. Telemetry, PRISM scoring, and all /prism:* commands continue to work.

If you’d rather edit the file directly:

# ~/.prism/config.json — set "enableGateway": false

To verify after restart: /prism:status should show Direct — bypass gateway.

Subscription auth (OAuth) is unaffected — gateway mode works with it out of the box.

Slow responses with gateway on

Gateway mode adds one extra network hop. If that’s unacceptable in your environment, temporarily switch to Direct:

Run /prism:status, say “toggle gateway”.
Restart Claude Code.
Telemetry, PRISM scoring, and all plugin commands continue to work in Direct mode. The only things you lose today are server-side request/response logging and the path governance features will plug into when they ship.

See Gateway Routing.

Reset everything

If nothing else works, do a clean reset:

/prism:uninstall — removes OTEL vars from both scopes, deletes ~/.prism/, unregisters the marketplace.
If anything remains: rm -rf ~/.prism ~/.claude/plugins/cache/optra-prism.
Reinstall: /plugin install prism (you’ll be prompted for a key).
Restart Claude Code.