トラブルシューティング

当てはまる症状を探し、原因と対処を確認してください。エラーコードはエラーコードに一覧があります。

コマンドが失敗する

症状	原因	対処
database_busy	ほかのコマンドかサーバーが、プロジェクトの書き込みロックを5秒を超えて保持した。	コマンドをもう一度実行します。続くなら、ロックを保持しているプロセスを探します。保存と復旧を参照。
task_is_draft	タスクが下書きで、エージェントは変更できない。	人にWeb画面で下書きを確定してもらい、その間はほかのタスクを進めます。TASK.mdは編集しません。
task_is_done	タスクがDoneで、エージェントは変更できない。	人に再開してもらいます。
acceptance_unmet	受入条件が未達成、またはfrontmatterが不正なタスクを、エージェントがDoneへ移そうとした。	条件を検証してdone: trueにするか（サーバーが自動で移します）、frontmatterを直します。
request_changed	質問がすでに回答された、移動で取り下げられた、または置き換えられた。	タスクを読み直し（show）、現在の依頼に回答します。
folder_unbound・bound_project_missing	作業フォルダがプロジェクトに紐付いていない、またはプロジェクトが削除された。	--projectでプロジェクトを明示するか、利用者にフォルダの紐付けを頼みます。
confirmation_required	削除に、端末での人のy/Nが必要。	人に実行してもらいます。確認を省くオプションはありません。

ボードの表示が想定と違う

症状	原因	対処
タスクがボードになく、problemsにtask.jsonが載る	ファイルが壊れている、formatVersionが1でない、または未知の項目がある。	problemsの項目を読みます。ファイル・項目・理由が書かれています。ファイルを手で直してください。Agent Boardによる自動修正は行いません。ファイルに不備があるときを参照。
本文に警告が出て、条件が空になる	TASK.mdのfrontmatterが正しいYAMLでない。	frontmatterを直します。その間も本文は表示されます。
CLIで変更しても画面が更新されない	serveが動いていない、通知が失われた、または共有領域がネットワークドライブにある。	ページを再読み込みします。変更はOSのイベントでも検知しますが、ネットワークドライブではイベントが届かないことがあります。変更の通知を参照。
エージェントが異常終了した後もタスクがRunningのまま	Runningは自己申告で、自動で戻すものはない。	タスクを移動するか、stateで状態を自分で設定します。
ボードに「切断」と出る	SSEの接続が切れた。	ブラウザが自動で再接続し、ボードを読み直します。

サーバーと待機

症状	原因	対処
already_serving	同じデータ領域で別のserveが動いている。	そちらを使うか、先に止めます。
port_in_use	別のプログラムがそのポートを使っている。	--portでほかのポートを選びます。7420は通常の利用のために空けておき、テストでは別のポートかポート0を使います。
waitやHookのboard_unavailable	serveが動いていない、または接続に失敗した。技術的な失敗で、回答ではない。	serveを起動し、waitを実行し直します。
cursor_invalid	cursorの形式が誤っている、または別のプロジェクトのもの。	同じプロジェクトのsnapshotから新しいcursorを取ります。
wait_timeout	任意の--timeoutが経過しても変更がなかった。	もう一度待ちます。質問はPendingのままです。

Hook

症状	原因	対処
context_too_largeのAGBOARD_ERROR	進行表が256 KiBを超える、または入力が64 KiBを超える。	完了したタスクを整理したり作業を分割したりして、進行表のサイズを減らします。有効な表を取得できるまで、ボードに依存する変更はしません。
folder_unboundのAGBOARD_ERROR	フォルダが紐付いていない。	フォルダをプロジェクトに紐付けるか、プロジェクトを明示します。
Hookが動かない	Hookが登録されていない、またはagboardがPATHにない。	連携の設定を見て、command -v agboardを確かめます。

ビルドとテスト

症状	原因	対処
cargo buildがRun "pnpm --dir web build" first.で止まる	RustのビルドはWeb画面を埋め込むが、画面がビルドされていない。	pnpm --dir web installとpnpm --dir web buildを実行してから、もう一度ビルドします。
変更がHook経由で反映されない	Hookは作業ツリーではなく、インストール済みのagboardを実行する。	cargo install --path . --locked --forceで入れ直します。開発環境のセットアップを参照。
テストがポート7420を使った、または自分のボードに触れた	テストが既定のポートやデータ領域を使った。	テストはAGBOARD_HOMEを一時ディレクトリにし、空いているポートかポート0を使います。
テストの時刻がマシンごとに違う	タイムゾーンが固定されていない。	TZ=UTCでテストを実行します。
pnpm --dir docs buildがリンク切れを報告する	ページが移動した、または見出しが変わった。	リンクを直します。リンク切れがあるとビルドは失敗します。