--- title: "Troubleshooting" description: "Describe how you want the work done. Auto builds a working playbook you can test, change and run again." url: "https://on.auto/docs/self-host/troubleshooting" last_updated: "2026-10-17T10:18:42Z" --- # Troubleshooting Each problem below gives the symptom, its usual cause and the fix. The first four are the ones people meet when they first start the server on their own computer. Never paste an API key into a prompt to fix a connection. The server reads keys from its own settings. ## The health check fails or port 5555 is busy **Symptom.** `curl http://localhost:5555/health` does not return `{"status":"ok"}`. **Cause.** The server did not start, or another process holds port `5555`. A server that cannot start prints `Auto Runtime could not start:` and the reason, such as `EADDRINUSE` for a port in use. In Docker, a second container on the same port fails with `port is already allocated`, and a second container with the same name fails with `is already in use`. **Fix.** * When your agent started Auto Runtime through its MCP entry, read `~/.auto-runtime/runtime.log` for startup errors, since the server has no terminal. Stop whatever else listens on port `5555`, or set `PORT` in `~/.auto-runtime/.env` to a free port; the entry reads it too. * With `npx @on.auto/runtime` in a terminal, read that terminal for startup errors. Stop whatever else listens on port `5555`, or set `PORT` in the `.env` of the directory you start it in to a free port, and give your agent that port: the command the server shows when it is ready carries it. * With Docker, run `docker logs auto-runtime` to read the startup errors. Stop and remove the earlier container before you start another with the same name or port: `docker stop auto-runtime && docker rm auto-runtime`. [Run with Docker](https://on.auto/docs/self-host/docker#start-the-server) keeps the command in a script that does this for you. ## The agent cannot connect, though `/health` responds **Symptom.** The health check returns `{"status":"ok"}`, but your agent shows `auto-runtime` as not connected. **Cause.** The agent has the wrong MCP entry or address, has not reloaded its connections, or runs somewhere that cannot reach your computer. A web-based connector running in the cloud cannot reach your `localhost`. **Fix.** * Check the agent's MCP entry. The [quick start](https://on.auto/docs/get-started/local#connect-your-agent) gives it: the `mcp` command of `@on.auto/runtime`, run by `npx`. An agent that connects over HTTP instead, as one that signs you in does, uses `http://localhost:5555/mcp`, or the port you set. * Restart the agent session. * Confirm that the agent runs on the same computer as Auto Runtime. ## A reasoning function reports `provider_not_configured` **Symptom.** A run of a reasoning function fails with `provider_not_configured`, or is rejected as `unavailable` of the kind `model_not_offered` with `because: "provider_not_configured"`. **Cause.** The definition names a provider whose settings the server did not find. The API hides missing settings and secrets from callers on purpose; the detail names only the providers that are configured. **Fix.** * Check which providers the server's startup log names. * With `npx`, check the setting in `~/.auto-runtime/.env` when your agent started Auto Runtime, or in `.env` in the directory you started it in from a terminal. With Docker, check `auto-runtime.env`. * Restart the server after you change a setting. With Docker, replace the container, since `docker restart` does not read the file again. * Confirm the provider prefix in the definition, and that the model id is available to your account. [Choose a provider](https://on.auto/docs/self-host/models#choose-a-provider) lists each provider's settings. ## The list of models is incomplete **Symptom.** `list_models` does not show the model you want, or shows only a wildcard such as `bedrock/*`. **Cause.** Some providers list no models of their own, an alias can hide the models it sends elsewhere, and `allowed_models` hides every model it does not allow, which the list shows as `narrowed: true`. **Fix.** Use a concrete model reference that your configured provider supports, such as a model id from the provider's own documentation. A wildcard such as `provider/*` is not a model to run. When the list says `narrowed: true`, a model it leaves out may be one that [`allowed_models`](https://on.auto/docs/reference/model-settings#allowed-models) does not allow, and a definition can name it only once the setting allows it. [Listing the models](https://on.auto/docs/reference/model-settings#listing-the-models) explains where each list comes from. ## The server says the identity service cannot be used **Symptom.** The server stops at start with an `UnusableIdentityServiceError`, naming the Auto identity service and each address it read. **Cause.** A runtime that signs people in reads the metadata and the key set of the Auto identity service, `https://clerk.on.auto`, as it starts. It could not reach them. **Fix.** * Check that the machine reaches `https://clerk.on.auto`. Where the machine has an outbound proxy, the server must go through it, as [Set up a model provider](https://on.auto/docs/self-host/models#behind-an-outbound-proxy-with-a-private-certificate-authority) sets out. * For development on a machine that cannot reach the service, remove `PUBLIC_URL` from `.env` and start the server again. A server on a loopback address without `API_KEYS` then runs in [local mode](https://on.auto/docs/self-host/security#local-mode), which signs no one in. ## The server stops at start, naming `PUBLIC_URL` and `API_KEYS` **Symptom.** The server stops before it listens, with a `ReachableWithoutCredentialsError`: `A server reachable beyond this computer needs PUBLIC_URL, to sign people in, or API_KEYS, and this one listens on HOST 0.0.0.0`. **Cause.** The server listens beyond loopback, as the Docker image does on `0.0.0.0`, and neither `PUBLIC_URL` nor `API_KEYS` is set. Anyone who reached it could otherwise act without a credential. **Fix.** * To sign people in, set `PUBLIC_URL`, as [Run with Docker](https://on.auto/docs/self-host/docker) does. * For machines and pipelines, set `API_KEYS` ([API keys](https://on.auto/docs/self-host/security#api-keys)). * For one person on their own computer, outside a container, set `HOST=127.0.0.1` instead. The server then runs in [local mode](https://on.auto/docs/self-host/security#local-mode). ## Error responses Every error is an [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem document (`application/problem+json`) with a machine-readable `reason`, such as: * `bad_request`; * `invalid_input`, with an `errors` list of JSON pointers; * `forbidden`; * `not_found`; * `conflict`. [Responses and errors](https://on.auto/docs/reference/http#responses-and-errors) lists every reason. A `500` says nothing about the cause. To find it in the log: 1. Read the response's `instance`, which is `urn:uuid:`, or its `x-request-id` header. 2. Search the server's stderr. The server logs the error under `"incident":""`, together with `"requestId"`, the value of `x-request-id`. Either id finds the line. A request that Node's HTTP parser rejects before the API sees it gets a bare status line, such as `431` or `400`, and no problem document. Oversized headers and invalid framing are rejected this way. ## The browser receives 403 **Cause.** The page's origin is not allowed, or, in local mode, the request's Host is not local. **Fix.** * Add the exact page origin to `ALLOWED_ORIGINS`. * Local mode also checks the request's Host. Never bypass these protections to expose local mode through a proxy. See [Authentication and security](https://on.auto/docs/self-host/security). ## Data disappeared after replacing a container **Cause.** The ledger lives on `/data`. A container started without a named volume gets an empty anonymous volume, and its playbooks last only as long as that container. **Fix.** Reuse the same named volume across container replacements. An anonymous volume is not a persistence plan. See [Back up and restore](https://on.auto/docs/self-host/docker#back-up-and-restore). ## Workflows are missing or unavailable Every server offers workflows and `send_run_event`, with nothing to configure. | Symptom | Cause and fix | | --- | --- | | A workflow does not go on | It is usually waiting: for an event, a timer or a function it called. Its history shows which | | The log warns about the runs | The server cannot do the work of its runs, and says what failed, such as `A sweep of the runs failed; the next sweep tries again`. [What the logs say](https://on.auto/docs/self-host/workflows#what-the-logs-say) lists them | | Workflow starts and run events return `unavailable` | Several servers share a database, and the request reached one that stands by. Its detail says another server runs the workflows, and each server's log says which it is. Route these operations as [Choose one server or a standby](https://on.auto/docs/self-host/production#run-several-servers) describes | ## A run stays started **Cause.** A waiting workflow can legitimately remain `started`. A run whose end the ledger could not record also stays `started` until a later attempt records it. **Fix.** * Read the run's history with `list_playbook_events`, given its `run_id`. It shows the run's steps, and the last one shows what the run waits for. * Check the log. The server warns once when such a run backs off to an attempt a minute, and once when it is settled. [Workflow storage and failover](https://on.auto/docs/self-host/workflows#how-a-run-ends) explains how a run ends. ## Sitemap See the [full documentation and product sitemap](https://on.auto/sitemap.md) for related pages.