Troubleshooting

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

/prism:status

It prints your API key prefix, the scope Prism is configured in, the endpoints in effect, and whether the OTEL vars are set correctly. Most issues surface there.

For deeper inspection, tail the debug log — it’s always written:

tail -f "${CLAUDE_PLUGIN_DATA:-$HOME/.prism/logs}/debug.log"

To also mirror debug output to your terminal (stderr), set "debug": true in ~/.prism/config.json. /prism:doctor reports whether it’s on and the exact file it writes to.

`/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 prism_* key.

Run /prism:setup prism_YOUR_KEY.
Confirm with /prism:status — it should show a prism_abc12… prefix.
Open the Connect panel in the dashboard header, copy the /prism:setup command it shows (your key is already filled in), and run it again to confirm the key is valid.

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 prism_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, re-run /prism:setup with your key and restart the session — that resets the address and the key together.
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.optra-prism.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 prism_* 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, treat the prism_* key as compromised: contact support through the dashboard to rotate it, then re-run /prism:setup with the replacement.
Re-run /prism:setup to reinstall the vars at the correct scope (user or project).

See Installation Scopes for the full rules.

Realtime summary not appearing

The realtime summary is off by default. Turn it on with:

/prism:config set show_realtime_summary true

If it’s on and still missing, tail the debug log — /prism:doctor reports whether debug logging is enabled and which file it writes to.

Reset everything

If nothing else works, do a clean reset:

Run /prism:uninstall. It previews exactly what it will remove, then removes only what Prism owns in the scope you’re uninstalling from.
Reinstall: /plugin install prism@optra-prism.
Run /prism:setup prism_YOUR_KEY.
Restart Claude Code.