Dépannage

Les problèmes courants et leurs solutions, recueillis à la fois sur le moteur Takuto Core et le Takuto CLI. Pour les problèmes de modèles auto-hébergés, voir Modèles auto-hébergés ; pour les problèmes de provisioning, voir Étendre Takuto Core.

Réseau et egress

npm ci échoue / « Exit handler never called »

Votre registre npm est bloqué par le firewall d’egress. Consultez le log de debug :

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

Ajoutez le domaine du registre à [network] extra_egress_hosts dans config.toml et redémarrez.

Claude Code « api_retry error: unknown »

L’endpoint d’API du fournisseur est bloqué. Le firewall d’egress autorise automatiquement les hôtes de chaque fournisseur listé dans [agent].available_providers ; commencez donc par vérifier que le fournisseur que vous utilisez y figure bien. Vérifiez ensuite l’accessibilité depuis l’intérieur du container :

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

Si un hôte reste injoignable (par ex. un endpoint d’éditeur dont les IP tournent, ou une passerelle auto-hébergée), ajoutez-le à [network] extra_egress_hosts.

Base de données

« Database backend unreachable » / pool timed out

La base externe dans [database] connection ne peut pas être atteinte depuis l’intérieur du container Takuto : il retombe alors sur l’ancien SQLite (ou avorte, si fail_fast = true). La cause habituelle est l’hôte de connexion : si la base tourne dans un container, la chaîne doit utiliser le nom de container de la base et son port interne (par ex. takuto_db:5432) — pas localhost ni le port publié sur l’hôte (par ex. localhost:5433), et les deux containers doivent partager un réseau. Voir Base de données externe pour le pas-à-pas complet et les chaînes de connexion par moteur.

Authentification

Auth introuvable après un rebuild ou un redémarrage

L’auth vit dans des volumes Docker. Si les volumes ont été supprimés, relancez le flux de setup :

# Avec le CLI
takuto auth

# En faisant tourner le moteur directement
docker compose run --rm -it takuto setup

takuto start / docker compose up se bloque après « Egress rules applied »

Le préflight d’auth est en cours. Un blocage ici vient généralement de agent status qui bloque sans TTY. Pour Cursor, définissez CURSOR_API_KEY dans takuto.env pour sauter le contrôle interactif ; sinon, reconstruisez l’image.

Erreurs de connexion Cursor Agent

Elles signifient toutes que vous êtes sur une couche d’image obsolète. Reconstruisez :

# Avec le CLI
docker compose -f takuto.yml build --no-cache

# En faisant tourner le moteur directement
docker compose build --no-cache

Symptômes que le rebuild corrige :

• bad option: --use-system-ca (une ancienne couche utilisait Node 20 ; l’image actuelle fournit un Node plus récent).
• /usr/local/bin/node: No such file or directory (binaire Node retiré d’une ancienne couche).
• Cannot find module '/usr/local/bin/index.js' (arbre cursor-agent incomplet).

Versions des outils du projet (mise)

L’image installe mise et construit les outils au premier lancement ; les installs persistent dans les volumes mise-data et mise-cache. Épinglez les runtimes par dépôt avec un fichier .mise.toml ou .tool-versions (par ex. Node, Python, Ruby).

Podman

Linux avec SELinux

docker-compose.yml définit security_opt: [label=disable]. Si vous devez conserver l’étiquetage SELinux, réétiquetez les volumes depuis l’hôte avec :z / :Z sur les bind mounts.

Conflits de noms de containers

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

macOS manque de mémoire

La VM de Podman a besoin de sa propre part de mémoire en plus du workflow. Donnez-lui-en plus avant de démarrer :

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

Logs

Les fichiers de log par workflow vivent à l’intérieur du container :

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

Le dashboard diffuse aussi la sortie terminal en direct sur chaque carte de workflow, et la rétention des logs par élément est contrôlée par [general] work_item_log_retention_days.

Toujours bloqué ?

Takuto Core est en bêta — si vous tombez sur quelque chose qui n’est pas couvert ici, vos retours sont sincèrement les bienvenus. Voir la FAQ pour savoir comment joindre l’auteur, et consultez la référence de configuration pour la clé exacte derrière un réglage.