トラブルシューティング

Takuto Core エンジンと Takuto CLI の両方から集めた、よくある問題とその対処法です。 セルフホストモデルの問題は セルフホストモデル を、provisioning の 問題は Takuto Core の拡張 を参照してください。

ネットワークと egress

npm ci が失敗する / 「Exit handler never called」

npm レジストリが egress firewall でブロックされています。デバッグログを確認します:

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

config.toml の [network] extra_egress_hosts にレジストリのドメインを追加して再起動します。

Claude Code の「api_retry error: unknown」

プロバイダーの API エンドポイントがブロックされています。egress firewall は [agent].available_providers のすべてのプロバイダーのホストを自動的に許可するので、まず 使っているプロバイダーがそこに記載されているか確認してください。次に container 内から到達性を 確認します:

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

それでも到達できないホストがある場合（例: IP がローテーションするベンダーのエンドポイントや、 セルフホストのゲートウェイ）は、[network] extra_egress_hosts に追加してください。

データベース

「Database backend unreachable」 / pool timed out

[database] connection の外部データベースに Takuto container の内側から到達できないため、 レガシーの SQLite にフォールバックしています（fail_fast = true の場合は中断します）。よくある 原因は 接続ホスト です: データベースを container で動かしている場合、文字列はデータベースの container 名とその内部ポート（例: takuto_db:5432）を使わなければなりません — localhost や ホスト側に公開したポート（例: localhost:5433）では なく、そして両方の container が同じ ネットワークを共有している必要があります。完全な手順とエンジンごとの接続文字列は 外部データベース を参照してください。

認証

リビルドや再起動のあとに認証が見つからない

認証は Docker ボリュームに置かれています。ボリュームが削除された場合は、セットアップフローを 再実行してください:

# With the CLI
takuto auth

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

takuto start / docker compose up が「Egress rules applied」のあとで止まる

認証のプリフライトが実行中です。ここでのハングは、たいてい TTY なしでブロックする agent status が原因です。Cursor の場合は takuto.env に CURSOR_API_KEY を設定して 対話式チェックをスキップしてください。それ以外の場合はイメージをリビルドします。

Cursor Agent のログインエラー

これらはすべて、古いイメージレイヤーにいることを意味します。リビルドしてください:

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

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

リビルドで直る症状:

  • bad option: --use-system-ca（古いレイヤーは Node 20 を使用。現在のイメージは新しい Node を 同梱）。
  • /usr/local/bin/node: No such file or directory（古いレイヤーから Node バイナリが削除）。
  • Cannot find module '/usr/local/bin/index.js'（不完全な cursor-agent ツリー）。

プロジェクトのツールバージョン（mise）

イメージは mise をインストールし、初回実行時にツールをビルドします。 インストールは mise-data と mise-cache ボリュームに永続化されます。リポジトリごとに .mise.toml または .tool-versions ファイルでランタイムを固定してください（例: Node、Python、Ruby）。

Podman

SELinux を使う Linux

docker-compose.yml は security_opt: [label=disable] を設定します。SELinux のラベリングを 維持しなければならない場合は、ホストからバインドマウントに :z / :Z を付けてボリュームを relabel してください。

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 でメモリ不足になる

Podman の VM は workflow とは別に、自分用のメモリ取り分を必要とします。起動前に増やして ください:

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

ログ

workflow ごとのログファイルは container 内にあります:

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

ダッシュボードも各 workflow カードでライブのターミナル出力をストリーミングし、項目ごとのログ 保持期間は [general] work_item_log_retention_days で制御されます。

まだ解決しませんか?

Takuto Core は ベータ です — ここでカバーされていないことに出くわしたら、あなたの フィードバックを心から歓迎します。作者への連絡方法は FAQ を、設定の背後にある 正確なキーは 設定リファレンス を参照してください。