Skip to content
Autonomous Engine Docs

Troubleshooting

Reading the logs

Start here for any problem:

Terminal window
docker compose ps                                  # which containers are up, restarting or unhealthy
docker compose logs -f <service>                   # follow one service
docker compose logs --tail=200 <service>           # recent lines only
docker compose logs status-orchestrator | grep -i migrat   # migration results

The service names are those in docker-compose.yml, such as status-orchestrator, knowledge-indexer, dashboard-backend and implementation-agent.

knowledge-indexer keeps restarting

Until an embedding provider exists, knowledge-indexer logs that none is configured and restarts. That is expected on a fresh install. Add one under Admin → Embeddings and it settles.

The build runs out of memory or gets killed

The stack builds many images. Build them one at a time:

Terminal window
COMPOSE_PARALLEL_LIMIT=1 docker compose build

Give Docker at least 16 GB of memory (in Docker Desktop: Settings → Resources), and more if the model runs on the same machine.

Windows: “Filename too long” when cloning or building

Clone into a short path such as C:\src\autonomous-engine, or enable long paths in git before cloning:

Terminal window
git config --global core.longpaths true

The dashboard won’t start

Check docker compose logs dashboard-backend. It refuses to start while JWT_SECRET is the placeholder or shorter than 32 bytes. Set it with openssl rand -hex 32 and run docker compose up -d again.

I can’t find the first-run admin password

status-orchestrator prints it once, the first time it creates admin@localhost:

Terminal window
docker compose logs status-orchestrator | grep -A4 "FIRST-RUN ADMIN"

Docker keeps a container’s logs only until the container is recreated, so read it soon after the first start.

Services can’t connect to the database

  • DB_PASSWORD goes into DATABASE_URL. Characters such as @, / or : break the URL. Use openssl rand -hex 16.
  • The postgres image sets the password only when it first creates its data volume. If you change DB_PASSWORD afterwards, the database keeps the old one. Change it inside PostgreSQL too, or, on a disposable install only, remove the volume with docker compose down -v (which deletes all data).

Migrations

status-orchestrator applies pending migrations from migrations/ every time it starts, and logs applied migration: <version> for each one. If a migration fails, it logs the error and keeps running without it, so check the log after every upgrade:

Terminal window
docker compose logs status-orchestrator | grep -i migrat

The engine can’t reach Ollama

Inside a container, localhost is the container itself. The dashboard suggests http://host.docker.internal:11434, which works on Docker Desktop. On Linux with Docker Engine that name doesn’t resolve by default, so use the host’s IP address, or add extra_hosts: ["host.docker.internal:host-gateway"] to the services that call the model.

For Ollama, use a model that supports tool calling. The engine stops instead of falling back to text-only generation.

A work item is blocked at verification

Check the work item’s evidence. Common causes:

  • No executable checks. The repository’s verification policy is fail-closed by default: if there is no test command or the required checks cannot run, verification blocks. Set a test command under the product’s verification policy, or let the product send such work to human review.
  • The verifier escalated. The verifier sends anything other than a small, actionable problem to human review instead of opening a pull request. Its verdict and reasons are on the work item.

Still stuck

Search the issues on GitHub, or open one with the output of docker compose ps, the logs from the failing service, and the version or commit you are running. Remove any secrets from logs before you post them. Report security problems privately, as described in Security.