Troubleshooting

Use this page when a recording does not produce the replay you expected.

Missing API key

If looma doctor cannot authenticate, create a new key from the dashboard and export it:

export LOOMA_API_URL=$NEXT_PUBLIC_APP_URL
export LOOMA_API_KEY=<token>
looma doctor

Make sure the key belongs to the same Looma app URL you are recording to.

For the full write-path check, run:

LOOMA_API_URL=$NEXT_PUBLIC_APP_URL LOOMA_API_KEY=<token> looma doctor --e2e

This creates a test session, records one event, stops it, and prints the replay URL.

No MCP tools

Run /mcp in Claude Code and confirm the looma server is listed. If record_start, record_event, and record_stop are missing, rerun setup:

looma setup claude-code --app-url $NEXT_PUBLIC_APP_URL --api-key <token>

Restart Claude Code after changing MCP configuration. The generated .mcp.json should use an absolute node .../dist/cli.js mcp command. If it still points to looma-mcp, upgrade the package and rerun setup:

npm i -g looma-agent@beta
looma setup claude-code --app-url $NEXT_PUBLIC_APP_URL --api-key <token>

No live updates

Check that the session is still recording, the agent hooks are installed in the active project, and the web app is connected to the expected Supabase project.

If the replay page is open, refresh /sessions/{sessionId} and confirm the event count changes after a new command or edit.

Replay stays processing

Processing starts after record_stop. If the replay never becomes ready, check the server logs for the session process route and confirm OPENAI_API_KEY is available when AI session notes or markers are generated.

You can still inspect raw captured events from the session API while processing is being fixed.

record_stop returns a server error

Use looma-agent@0.1.0-beta.1 or newer and make sure the Looma database includes the one-to-one replay metadata migration. record_stop should be safe to call when Claude Code hooks are active.

Secrets or redaction concerns

Do not send secrets through record_event. If a tool output may contain secrets, redact it before it reaches Looma or mark it as sensitive.

Replay renderers should use redacted payloads by default. If you see private values in a replay, rotate the exposed secret and remove the unsafe event payload from storage.