Troubleshooting¶
In short
- Most connection problems are reachability (web hosts need public HTTPS) or a token's scope.
- A tool missing from the list usually means the token's scope does not include it.
- The agent-facing cause and fix for each API error is in the playbook's errors topic.
The agent-facing cause→fix catalog is the playbook's errors topic; this page adds the host-side issues.
| Symptom | Cause → fix |
|---|---|
| Web host (claude.ai / ChatGPT) can't connect | It calls from its servers — parleml must be on public HTTPS. See the reachability matrix. |
Claude Desktop ignores a url/headers entry in its local JSON |
Use a local stdio command/args entry, or add a remote OAuth connector through Settings → Connectors. The remote connector needs public HTTPS even in Desktop (setup). |
VS Code does not recognize .vscode/mcp.json |
Use servers, with type: "http", URL and headers in each entry; see IDE setup. |
| 401 on every call | Auth gate is on and no/expired token — mint in Settings → Access; check the Authorization header survives your proxy. |
probe_dataset / what_if / simulate_decision missing from the tool list, or "needs a 'compute' token" (or 403) on them or on compare with kind="datasets" |
Token has the analyst scope — mint a compute token (scopes). After switching tokens, reconnect (or wait a minute) before listing tools again. |
The builder tools (run_experiment, author_recipe, …) are missing, or "needs a 'builder' token" |
Mint a builder token bound to the workspace (scopes), or do the step in the parleml UI. |
Every call 401s with reason token_refused |
ParleML refuses the token: a scope name it does not know, or a builder token without an expiry. Mint a new one. |
| "cannot reach the parleml backend" on every tool | The backend is not running, or PARLEML_API_BASE points elsewhere. Report it — retrying will not help. |
| A read or compute tool times out | Most metadata reads use a 30-second request timeout; some compute calls have their own bounds. Cached signal probes can keep computing: use the returned wait handle, or repeat the same probe to read its cached result; for query_sql, narrow the query or lower limit. |
| A builder tool times out | The call may still be running. In a session ParleML runs, wait once with the session tool await_operation (operation_id="call:<key>"; the message names the handle), then repeat the call with the idempotency_key the message gives; elsewhere retry with that key — never with fresh arguments; 409 idempotency_key_in_use means it is still running. |
An agent's tool call fails with ECONNRESET (or fetch failed) and the server logged nothing |
The server closed an idle keep-alive connection just as the CLI reused it: uvicorn's default --timeout-keep-alive (5 s) is barely above Node's own idle timeout (4 s). Start the API with --timeout-keep-alive 75, as the Docker image does. A builder call is safe to repeat with the idempotency_key you passed (or one a result gave you): it replays instead of acting twice. |
| The agent greps a saved file for a tool result | The host filed away a result over its inline limit (Claude Code: ~50,000 characters). Every model view stays under 25,000 characters; a result that still overruns is a bug — report the tool call (conformance/test_response_budget.py pins the recorded ones). |
Unknown insight kind / Unknown chart kind |
The error carries the allow-list — pick from it rather than inventing a name. get_insight(id, "kinds") lists the kinds that apply to that experiment. |
| Tools hang behind a reverse proxy | Streamable-HTTP being buffered — disable response buffering for /mcp. |
ui_url links point at a host with no UI (e.g. http://localhost:8000/… in local dev) |
The UI isn't served from the origin the agent reached /mcp on → set PARLEML_PUBLIC_URL to the UI's origin (local dev). |
| Spurious "Internal Server Error" notices on Windows stdio | Blank lines on stdin. The server filters them; check that your stdio wheel matches the running backend. |
get_chart_data(..., render="png") returns png_unavailable |
Use the returned numeric data and read the reason. A missing dependency, unavailable browser or transient renderer failure can prevent PNG output; check the serving environment before installing packages. |
| Skills and MCP both loaded, double guidance | Expected: the skills add routing guidance, the MCP tool descriptions and get_playbook are authoritative. Prefer the tool descriptions where they differ. |
| Version-skewed standalone wheel | Typed output schemas are strict on purpose — rebuild the wheel against the running backend (export_mcp_schemas.py + uv build). |
| The server refuses to start: "… was built for 'mcp-apps/…'" | The App templates were built for another MCP Apps contract — rebuild them (npm run build:embed in apps/web). |