Troubleshooting

Common issues and their fixes, gathered from both the Takuto Core engine and the Takuto CLI. For self-hosted model problems see Self-hosted models; for provisioning issues see Extending Takuto Core.

Network and egress

`npm ci` fails / “Exit handler never called”

Your npm registry is blocked by the egress firewall. Check the debug log:

docker exec -u takuto <container> tail -30 /home/takuto/.npm/_logs/*-debug-0.log

Add the registry domain to [network] extra_egress_hosts in config.toml and restart.

Claude Code “api_retry error: unknown”

The provider’s API endpoint is blocked. The egress firewall clears the hosts for every provider in [agent].available_providers automatically, so first confirm the provider you are using is listed there. Then verify reachability from inside the container:

docker exec -u takuto <container> curl -s -o /dev/null -w "%{http_code}" https://api.anthropic.com

If a host still can’t be reached (e.g. a vendor endpoint that rotates IPs, or a self-hosted gateway), add it to [network] extra_egress_hosts.

Database

”Database backend unreachable” / pool timed out

The external database in [database] connection can’t be reached from inside the Takuto container, so it falls back to legacy SQLite (or aborts, if fail_fast = true). The usual cause is the connection host: if the database runs in a container, the string must use the database container name and its internal port (e.g. takuto_db:5432) — not localhost or the host-published port (e.g. localhost:5433), and both containers must share a network. See External database for the full walkthrough and per-engine connection strings.

Authentication

Auth not found after a rebuild or restart

Auth lives in Docker volumes. If the volumes were deleted, re-run the setup flow:

# With the CLI
takuto auth

# Running the engine directly
docker compose run --rm -it takuto setup

`takuto start` / `docker compose up` stalls after “Egress rules applied”

The auth preflight is running. A hang here is usually agent status blocking without a TTY. For Cursor, set CURSOR_API_KEY in takuto.env to skip the interactive check; otherwise rebuild the image.

These all mean you’re on an outdated image layer. Rebuild:

# With the CLI
docker compose -f takuto.yml build --no-cache

# Running the engine directly
docker compose build --no-cache

Symptoms that the rebuild fixes:

bad option: --use-system-ca (old layer used Node 20; the current image ships a newer Node).
/usr/local/bin/node: No such file or directory (Node binary removed from an old layer).
Cannot find module '/usr/local/bin/index.js' (incomplete cursor-agent tree).

Project tool versions (mise)

The image installs mise and builds tools on first run; installs persist in the mise-data and mise-cache volumes. Pin runtimes per repository with a .mise.toml or .tool-versions file (e.g. Node, Python, Ruby).

Podman

Linux with SELinux

docker-compose.yml sets security_opt: [label=disable]. If you must keep SELinux labeling, relabel volumes from the host with :z / :Z on the bind mounts.

Container name conflicts

podman stop -a && podman rm -f $(podman ps -aq) 2>/dev/null
podman pod rm -f $(podman pod ls -q) 2>/dev/null

macOS runs out of memory

Podman’s VM needs its own memory share on top of the workflow. Give it more before starting:

podman machine stop && podman machine set --memory 12288 --cpus 4 && podman machine start

Logs

Per-workflow log files live inside the container:

docker exec <container> cat /workspace/logs/<TICKET-KEY>.log

The dashboard also streams live terminal output on each workflow card, and per-item log retention is controlled by [general] work_item_log_retention_days.

Still stuck?

Takuto Core is in beta — if you hit something not covered here, your feedback is genuinely welcome. See the FAQ for how to reach the author, and check the configuration reference for the exact key behind a setting.