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 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 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 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 does not allow, and a definition can name it only once the setting allows it. 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 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, 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 does.
• For machines and pipelines, set API_KEYS (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.

Error responses

Every error is an RFC 9457 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 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:<id>, or its x-request-id header.
2. Search the server's stderr. The server logs the error under "incident":"<id>", 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.

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.

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 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 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 explains how a run ends.