Troubleshooting

Troubleshooting

Agents

The agent starts, then retries forever with Connection refused

WRIT_PUBLIC_URL is wrong. The coordinator derives the WebSocket URL it hands back from that value, so if it says localhost while the agent is on another machine — or names the wrong port — the agent dials somewhere that is not there and nothing explains why.

curl -s https://writ.example.com/api/fleet/connect-info \
  -H "Authorization: Bearer <token>" | grep ws_url

That is the URL your agent will actually use. Fix WRIT_PUBLIC_URL in .env and restart the coordinator.

another Writ daemon is already running for this home

Two workers cannot share one WRIT_HOME. Either stop the other one, or give this agent its own directory:

WRIT_HOME=~/.writ-second writ-agent-fleet

WRIT_COORDINATOR_URL (or SAAS_URL) is not set

writ-agent-fleet is configured entirely by environment. It has no config file and no config subcommand — that belongs to the separate desktop writ-agent binary. Pass WRIT_COORDINATOR_URL in the environment.

"No published release asset for …"

The agent repository has no release for your platform yet. Build from source:

cargo build --release --no-default-features --features local,fleet,openai --bin writ-agent-fleet

The agent is online but nothing runs

Check free capacity in Fleet. An agent advertises a bounded number of slots from its resource governor, not raw CPU count. If they are all busy, work queues.

"Run an agent on this host" is disabled

Expected on a Docker install. A container has no host process table and no browser runtime, so it cannot launch an agent on your machine. Use the one-line installer instead.

Recording

Step 2 sits on "Loading browser…"

The agent has to launch a real browser, which takes a few seconds cold. If it never arrives, check the agent log for CDP screencast started. If the session opened but no frames flow, the agent is likely on a build that predates the recorder fix — rebuild it.

Clicks land on the wrong element

Fixed in current builds; it was a screencast/context resolution mismatch that scaled every coordinate. Rebuild your agent if you are on an older binary.

Documents

A crawl returned no PDFs

DOC_EXTRACT_URL is unreachable from your agents. The failure is silent by design — an agent with no extractor skips non-HTML content and reports success.

curl -s https://writ.example.com/api/fleet/connect-info \
  -H "Authorization: Bearer <token>" | grep doc_extract

If agents are on other machines, the loopback default cannot work. See Documents and OCR.

Coordinator

It refuses to boot on secrets

Any required secret that is missing, blank or under 32 characters stops the boot. Run ./scripts/gen-env.sh, or fill the named variable by hand. This is deliberate — see Security model.

400 Bad Request from a browser

ALLOWED_HOSTS does not include the hostname you used. Visiting via 127.0.0.1 when the allowlist says localhost is enough to trigger it. Add both if you use both.

It refuses to start with more than one worker

By design. Remove WEB_CONCURRENCY / WORKERS / UVICORN_WORKERS, or set them to 1. Scale with agents. See Production deployment.

/docs and /openapi.json return 404

Expected in production. Set WRIT_EXPOSE_OPENAPI=true to re-enable.

The database is growing quickly

Check WRIT_FILES_DIR is set. Without it, screenshots and uploads are base64-encoded into SQLite instead of written to disk. Then review the retention windows in Configuration.

MCP

API key is missing the 'mcp:execute' scope

Exactly what it says. The MCP endpoint checks that scope specifically — add it to the key alongside the resource scopes.

Getting help

Logs first:

docker compose logs -f coordinator
docker compose logs -f doc-extract
tail -f ~/.writ/agent.log

Then open an issue or ask in Discussions. For a security problem, use private reporting instead.