Solución de problemas

Problemas comunes y sus arreglos, recopilados tanto del motor Takuto Core como de la Takuto CLI. Para problemas de modelos autoalojados consulta Modelos autoalojados; para problemas de provisioning consulta Extender Takuto Core.

Red y egress

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

Tu registro de npm está bloqueado por el egress firewall. Revisa el log de debug:

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

Añade el dominio del registro a [network] extra_egress_hosts en config.toml y reinicia.

Claude Code “api_retry error: unknown”

El endpoint de la API del proveedor está bloqueado. El egress firewall habilita automáticamente los hosts de todos los proveedores de [agent].available_providers, así que primero confirma que el proveedor que estás usando figura ahí. Luego verifica la alcanzabilidad desde dentro del container:

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

Si un host sigue sin ser alcanzable (p. ej. un endpoint de proveedor que rota IPs, o un gateway autoalojado), añádelo a [network] extra_egress_hosts.

Base de datos

”Database backend unreachable” / pool agotó el tiempo

La base de datos externa de [database] connection no es alcanzable desde dentro del container de Takuto, así que recurre al SQLite heredado (o aborta, si fail_fast = true). La causa habitual es el host de la conexión: si la base de datos corre en un container, la cadena debe usar el nombre del container de la base de datos y su puerto interno (p. ej. takuto_db:5432) — no localhost ni el puerto publicado en el host (p. ej. localhost:5433), y ambos containers deben compartir una red. Consulta Base de datos externa para el recorrido completo y las cadenas de conexión por motor.

Autenticación

No se encuentra la auth tras un rebuild o reinicio

La auth vive en volúmenes de Docker. Si los volúmenes se borraron, vuelve a ejecutar el flujo de setup:

# With the CLI
takuto auth

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

`takuto start` / `docker compose up` se estanca tras “Egress rules applied”

El preflight de auth está corriendo. Un cuelgue aquí suele ser agent status bloqueándose sin un TTY. Para Cursor, fija CURSOR_API_KEY en takuto.env para saltarte la comprobación interactiva; si no, reconstruye la imagen.

Todos significan que estás en una capa de imagen desactualizada. Reconstruye:

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

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

Síntomas que el rebuild arregla:

bad option: --use-system-ca (la capa antigua usaba Node 20; la imagen actual incluye un Node más nuevo).
/usr/local/bin/node: No such file or directory (binario de Node eliminado de una capa antigua).
Cannot find module '/usr/local/bin/index.js' (árbol de cursor-agent incompleto).

Versiones de herramientas del proyecto (mise)

La imagen instala mise y construye las herramientas en la primera ejecución; las instalaciones persisten en los volúmenes mise-data y mise-cache. Fija los runtimes por repositorio con un archivo .mise.toml o .tool-versions (p. ej. Node, Python, Ruby).

Podman

Linux con SELinux

docker-compose.yml fija security_opt: [label=disable]. Si debes mantener el etiquetado de SELinux, reetiqueta los volúmenes desde el host con :z / :Z en los bind mounts.

Conflictos de nombre de container

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

macOS se queda sin memoria

La VM de Podman necesita su propia parte de memoria además de la del workflow. Dale más antes de arrancar:

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

Logs

Los archivos de log por workflow viven dentro del container:

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

El dashboard también transmite la salida de terminal en vivo en cada tarjeta de workflow, y la retención de logs por ítem se controla con [general] work_item_log_retention_days.

¿Sigues atascado?

Takuto Core está en beta — si te topas con algo no cubierto aquí, tu feedback es genuinamente bienvenido. Consulta las FAQ para saber cómo contactar con el autor, y revisa la referencia de configuración para el comportamiento exacto detrás de un ajuste.