Troubleshooting

Plugin not loading

Symptom: /prism:help returns “unknown command”

Fix:

1. Verify the plugin is installed: check marketplace or ~/.claude/plugins/
2. Restart Claude Code
3. Reinstall: /plugin marketplace add grumatic/optra-prism-plugin

”Invalid API key” on session start

Symptom: session start shows an error about key validation

Fix:

1. Check your key starts with gck_ — run /prism:status to see the current key prefix
2. Re-run setup: /prism:setup gck_YOUR_KEY
3. Verify the key is active in the dashboard
4. Check legacy config if using it: cat ~/.prism/config.json

No telemetry data in dashboard

Symptom: dashboard shows empty charts and no sessions

Fix:

1. Check OTEL settings are synced: /prism:status — verify OTEL endpoint URLs are set
2. Verify ingest service is reachable: the URLs should point to your environment’s ingest endpoint
3. Check that your API key has not expired
4. Wait a few minutes — data processing has a short delay as sessions are batched and written to S3

Prompt advisor not showing suggestions

Symptom: all prompts pass through silently, no PQ feedback

Possible causes:

• The prism-advisor skill is the always-active advisor — check it’s loaded by running /prism:help
• Prompts are too short (<10 chars) or are slash commands (these are skipped)
• You gave advice on the immediately preceding turn (never advises twice in a row)
• The prompt already contains file paths, error messages, or code snippets (considered good enough)

Fix: run /prism:advisor to trigger a detailed analysis manually, or try a vague prompt like “fix the bug” to see if the advisor activates.

Status line not showing

Symptom: no [Prism] line appears after responses

Fix:

1. Check that showStatusLine is enabled: /prism:status
2. Toggle it on: /prism:status toggle status line
3. Restart Claude Code if the setting was just changed

Config endpoint not resolving URLs

Symptom: session start shows “Could not resolve service URLs”

Fix:

1. Check network connectivity to ingest.prism.optra-ai.com
2. Re-run /prism:setup gck_YOUR_KEY to refresh the config cache
3. For local development, set URLs directly: PRISM_INGEST_URL=http://localhost:9005 claude
4. Check the cache file: cat ${CLAUDE_PLUGIN_DATA}/config-cache.json (or ~/.prism/config-cache.json)

Gateway routing not working

Symptom: /prism:status shows gateway enabled but requests still go to Anthropic directly

Fix:

1. Restart Claude Code (environment variables are set on session start)
2. Check ANTHROPIC_BASE_URL is set: /prism:status should show the gateway URL
3. If you have other tools setting ANTHROPIC_BASE_URL, there may be a conflict

Slow responses with gateway enabled

Symptom: response times increase significantly with gateway routing on

Fix:

1. Toggle to telemetry-only mode: /prism:status toggle
2. This removes the gateway hop and routes directly to Anthropic
3. You keep all scoring and analytics — only budget enforcement and guardrails are affected

OTEL settings conflict

Symptom: another tool or plugin also sets OTEL environment variables

Fix: The Prism plugin checks OTEL settings on every session start. If they’ve drifted, it syncs them and tells you to restart. If another tool constantly overwrites them, you may need to uninstall the conflicting tool or disable Prism’s OTEL sync by uninstalling the plugin.

Reset everything

If all else fails, do a clean reset:

# Remove config and cache
rm -rf ~/.prism

# Re-setup (this also refreshes the config cache)
/prism:setup gck_YOUR_KEY

# Restart Claude Code