Skip to main content

​
Quickstart (Claude Code) run failed?

The rest of this page assumes the Pome CLI. If you came through the Claude Code quickstart, you likely don’t have it installed. Debug from the conversation instead:
  • Ask the coach for the report again: get_report(run_id) names each criterion, its verdict, and what the judge saw.
  • finalize_run errored. Read the error text first. If it says the session is still live, the failure is retryable (a capture or transient server error) and the session is preserved: call finalize_run again with the same session_id instead of re-running anything. Only an expired session is unrecoverable — it cannot be scored, so re-run steps 5–8 of the quickstart prompt and finalize the moment the examinee exits.
  • Pome tools missing. Check the connection with claude mcp list, then re-authenticate from the /mcp menu inside Claude Code.
  • The dashboard link in every report shows the full trace and judge feedback.

​
Debugging with the CLI

Start with pome inspect latest. It usually points at the layer that failed: task, agent, twin, or judge.

​
Agent crashed

Most common causes:
  • Agent did not no-op on POME_PREFLIGHT=1.
  • Agent ignored POME_GITHUB_REST_URL and hit the real internet.
  • Task prompt referenced state the agent could not parse.

​
Score below 100

If a call has fidelity: "unsupported", the agent reached for an endpoint the twin does not implement yet. File an issue at github.com/pome-sh/digital-twins.

​
Twin will not start

A port is stuck:
To check whether the twin process is alive, hit the unauthenticated root health endpoint:
The session-scoped /s/<sid>/healthz requires the JWT and returns 401 without it.

​
Hosted run hangs or 401s

Re-mint your key:
Or set POME_API_KEY directly in CI.

​
The hosted upload rejects my events.jsonl schema

The hosted upload requires the discriminated-union RecorderEvent schema. Upgrade the CLI:
Then re-run.

​
pome fix-prompt says “no failures” for a failed hosted run

Hosted runs do not yet surface per-criterion verdicts to the CLI. If you see the message verdicts not available, open cloud run URL, or re-run POME_LOCAL=1 to enable local judge, do one of:
  • Open the run URL printed by pome run and read the judge feedback in the dashboard.
  • Re-run with POME_LOCAL=1 pome run <task> to use the local judge, which writes per-criterion verdicts to disk.
The cloud-side fix is in flight.

​
pome login says “already logged in” but I do not see ~/.pome/credentials.json

On macOS, pome stores the key in the Keychain by default:
On Linux/Windows, or when the Keychain is unavailable, the key falls back to ~/.pome/credentials.json. Both paths are valid; the CLI tries the env var, then the Keychain, then the JSON file.

​
pome run exits 2 or 3 when you expected 1

A few exit-code paths have known regressions. A sub-threshold hosted run can return exit code 2 or 3 instead of the documented 1; a failing pre-flight (missing task file, logged-out state) can also return 2 instead of 5 or 3. The documented contract in CLI reference is the intent. If your CI branches on $?, treat exit codes as advisory for now. The dashboard run URL is the source of truth for pass/fail.

​
pome run --api-url http://... does not change the destination

The --api-url flag is currently dropped on the way to the hosted client. Use the env var as a workaround:
The flag will be fixed in a follow-up release.

​
pome session list returns more rows than the dashboard

The CLI defaults to --state running, but if you have ever passed --state all, that selection persists in your shell history. The dashboard’s Twins page defaults to running sessions. To match it:

​
pome session create prints two identical URLs and my agent’s MCP transport fails

Hosted session text output currently prints the MCP URL without the /mcp suffix, so it looks identical to the REST API URL. An agent that mounts that URL as an MCP transport gets REST responses and fails to negotiate the handshake. Workaround: append /mcp to the printed URL when configuring your agent.
The standalone pome twin start github path emits the suffix correctly.