---
title: "エラーコード索引 — codeから意味と次の操作を引く"
description: "aachatのAPI server、chat、aachat、doctor、status、Launch Report、Session起動が返すエラーcodeを、意味と次の操作、詳しいページへのリンクで引ける索引。"
---

# エラーコード索引 — codeから意味と次の操作を引く

手元に`error.code`や表示されたcodeがあるときに、意味と次の操作を引くページである。症状から調べるときは[トラブルシューティング](/ja/docs/troubleshooting)を読む。

codeは、どこで見たかで読む節が変わる。同じ失敗でも、WebUI・`chat`・`aachat`で表示が違うことがある。

| codeを見た場所 | 読む節 |
|---|---|
| WebUI、HTTP APIの応答 | [serverのエラーコードの読み方](#serverのエラーコードの読み方)と、機能ごとの節 |
| Session内の`chat`の出力 | [`chat` CLI（Session内）のエラーコード](#chat-clisession内のエラーコード)と、機能ごとの節の「chatでの表示」列 |
| `aachat`の出力 | [`aachat` CLIのエラーコード](#aachat-cliのエラーコード) |
| `aachat doctor`の`issues[]` | [`aachat doctor`の項目とcode](#aachat-doctorの項目とcode) |
| `aachat status`の`warnings[]` | [`aachat status`の`warnings[]`と状態の値](#aachat-statusのwarningsと状態の値) |
| `up.log`のLaunch Report | [Launch Reportのカテゴリ](#launch-reportのカテゴリ) |
| Sessionの起動・失敗の表示 | [Sessionの失敗と起動時のcode](#sessionの失敗と起動時のcode) |

どの場合も、codeだけで判断せず`message`と`hint`も読む。成否がわからない変更操作は、同じ操作を重ねる前に、最初の操作が受け付けられたかを確認する。

## serverのエラーコードの読み方

aachatのAPI serverは、失敗するとHTTP statusと`{"error": {"code": ..., "message": ...}}`の形の本文を返す。`error`には`input`（受け取った値）や`existing_session_id`が付くことがあり、一部の失敗では本文に`data`も付く。`code`はほとんどが大文字（`VALIDATION_ERROR`・`NOT_FOUND`・`SESSION_NOT_RUNNING`など）で、Project・Ask・Workflowなどの一部は小文字（`project_not_active`・`ambiguous_id`・`draft_version_conflict`など）である。

同じ失敗でも、読む場所によってcodeの見え方が違う。

| 読む場所 | 見えるcode |
|---|---|
| WebUI、HTTP API | serverのcodeそのまま |
| `chat`（Session内） | `chat`が小文字の自分のcodeへ読み替える。下の各表の「chatでの表示」列。serverの説明文は`message`に入り、`chat`の案内は`hint`に入る |
| `aachat` | さらに少数のcode（`permission_denied`・`auth_required`・`prerequisite_missing`・`internal_error`など）へ読み替える。[`aachat` CLIのエラーコード](#aachat-cliのエラーコード)を読む |

`chat`の読み替えは次の規則で決まる。

- HTTP 400・422は`invalid_argument`になる。例外は`ambiguous_id`・`AMBIGUOUS_PROJECT`・`AMBIGUOUS_USER`・`USER_NOT_FOUND`・`REPLY_TARGET_NOT_FOUND`・`INVALID_REPLY_TARGET`で、それぞれ小文字の同名codeになる
- 401は`token_required`、403は`not_authorized`（`ADMIN_REQUIRED`などの専用codeは除く）、409は`conflict`、429は`network_error`、5xxは`server_error`になる
- 404は`message`の語で決まる。`session`を含めば`session_not_found`、`agent`を含めば`agent_not_found`、`blueprint`・`repository`を含めば`unexpected_response`、それ以外は`project_not_found`である
- structuredなserver codeをstatusのfallbackより先に判定する。たとえば`VALIDATION_ERROR`はHTTP 413でも`invalid_argument`になる。一致するcodeがなければ、410・413・426などのstatusは`unexpected_response`になる
- Workflowの検証・状態のcode（`invalid_workflow_yaml`・`draft_version_conflict`など）は、Workflow系のコマンドでは小文字のまま通る
- 送信後に応答が得られなかった変更操作や、HTTP 408・429・5xxを受けた一部の変更操作（`project create`・`project assign`・`workflow init`・`workflow run`（`--wait`を含む）・`workflow retry`・`workflow complete`・`wait`・`trigger create`・`trigger run`。Workflowの変更操作は接続失敗でも同じ）は`operation_outcome_unknown`になる。新しい要求を作らず、そのcommandの`message`と`hint`に従う。`commands`があれば各commandの用途を読む（[同じ要求の再送](/ja/docs/cli#同じ要求の再送)）

`operation_outcome_unknown`からの回復はcommandごとに異なる。

- `workflow init/run/retry`と`wait`は、`commands`の回復commandをそのまま使い、同じnonce・引数・入力を保つ。変更操作の場合もあり、新しいnonceを生成しない
- `workflow complete`は`commands`がなくても、同一payloadを同じ閉じた非対話入力から再送し、応答の`accepted:true`を確認する。受付はWorkflowや製品の成功とは別である
- `project create`と`project assign`は`commands`が必須ではない。`hint`に従い、createは同じ引数とstdin、assignは同じProjectとagentで回復する。commandが対応していないnonce指定を足さない
- `trigger create`と`trigger run`のlist/show commandは現在のTriggerを照合する読取りである。現状態を確認してから次の操作を判断する

表の「chatでの表示」が「同じ」ならserverのcodeがそのまま出る。「—」はWebUI・人間専用の操作など、`chat`からは届かないcodeである。

## 汎用のcode

どの機能でも返るcode。まずHTTP statusで大まかに判断し、`message`で原因を読む。

| code（HTTP） | chatでの表示 | 意味 | 次の操作 |
|---|---|---|---|
| `VALIDATION_ERROR`（400・422） | `invalid_argument` | 入力が不正である。理由は`message`にある | `message`に合わせて値や引数を直す |
| `VALIDATION_ERROR`（413） | `invalid_argument` | 入力が大きすぎる | 小さくするか分割して送り直す（[容量・実行条件](/ja/docs/limits#上限に関係するエラーが出たら)） |
| `NOT_FOUND`（404） | 上の404の規則による（`skill feedback`では`session_not_active`、`wait show`では`wait_not_found`） | 対象がない、または見えない。存在しないのか権限がないのかは区別しないことがある | 一覧でIDや名前を確かめて指定し直す |
| `CONFLICT`（409） | `conflict`（`message`に`session is not running`を含めば`session_not_running`） | 現在の状態と衝突した。他から参照されているものの削除は`Cannot delete: referenced by other records`になる | 最新の状態を読み直してから判断し直す。同じ要求をそのまま繰り返さない |
| `CONFLICT`（412） | `conflict` | 送ったversionなどの前提が古い | 最新を読み直し、新しいversionで要求を作り直す |
| `UNAUTHORIZED`（401） | `token_required` | 認証がない・無効・使えない（`Not authenticated`・`Invalid token`・`This account is no longer available`） | [認証で失敗する](/ja/docs/troubleshooting#認証で失敗する)を読む。Session内なら人間に`aachat up`の状態確認を依頼する |
| `FORBIDDEN`（403） | `not_authorized`（`edit`・`delete`では`message_mutation_failed`、`skill feedback`では`forbidden`） | 権限がない。理由は`message`にある | 下の[権限・範囲](#権限範囲)を読む |
| `RATE_LIMITED`（429） | `network_error` | 短時間の要求が多すぎる。認証の入口では`Too many requests. Please try again later.`になる | 時間をおいて再実行する。`Retry-After`があればその秒数を待つ（Webhookだけが付ける） |
| `GONE`（410） | `unexpected_response` | 期限切れ・無効になったものを使った（例：`Wiki snapshot expired; refresh the list`、`This client entry link has expired. Ask the team to reissue it.`） | 一覧を読み直す、またはリンクの再発行を依頼する |
| `STORAGE_UNAVAILABLE`（503） | `server_error` | 保存先が一時的に使えない | 時間をおいて再実行する |
| `INTERNAL_ERROR`（500） | `server_error` | server内部の失敗（`Internal server error`・`Database error`） | 変更操作なら、再送の前に反映されたかを読んで確かめる。続く場合は[supportへ渡す](/ja/docs/troubleshooting#失敗した操作の診断をsupportへ渡す) |
| `INTERNAL_ERROR`（500、本文に`data`あり） | `server_error` | 一部は保存済みで、その後の処理が失敗した（例：`Workflow changes were saved, but subsequent notification or observation failed; inspect the saved target before retrying.`） | 保存された対象を読んでから、残りだけをやり直す |
| `DATABASE_PROVISIONING_CONFLICT`（500）など運用側の内部code | `server_error` | 利用者側では直せない内部状態の不整合 | SQLや秘密情報を含めずに、時刻・Project・codeを添えて報告する |

## 権限・範囲

| code（HTTP） | chatでの表示 | 意味 | 次の操作 |
|---|---|---|---|
| `FORBIDDEN`（403） | `not_authorized`（`edit`・`delete`では`message_mutation_failed`、`skill feedback`では`forbidden`） | 操作の権限がない。`message`が理由を示す（`Owner access required`・`Owner or admin access required`・`Only the session owner or session agent can access this session`・`Agent session does not cover this project`・`Cannot remove or leave as the last human project admin`など） | `message`の条件を満たす人に操作か権限付与を依頼する（[拒否されたときの確認順](/ja/docs/permissions#拒否されたときの確認順)） |
| `ADMIN_REQUIRED`（403） | `admin_required` | Project adminの権限が必要である（`Admin access required`） | Project adminに操作か権限付与を依頼する |
| `COLLABORATOR_REQUIRED`（403） | `collaborator_required`（`edit`・`delete`では`message_mutation_failed`） | Projectへの書込み権限（collaboratorまたはadmin）が必要である（`Collaborator access required`） | 書込み権限のあるmemberに追加を依頼するか、書けるProjectを選ぶ |
| `PROJECT_OUT_OF_SCOPE`（403） | `project_out_of_scope`（`edit`・`delete`では`message_mutation_failed`） | 現在のSessionが扱う範囲の外のProjectである（`Project is outside the current session scope`） | そのProjectを扱うSessionから実行する |
| `CROSS_PROJECT_READ_ONLY`（403） | `cross_project_read_only` | 他のProjectは読めるが、変更や仕事の開始はできない | 自分のProjectで報告し、人間かそのProjectのLeadに任せる（[Sessionから他Projectを横断閲覧する](/ja/docs/projects#sessionから他projectを横断閲覧する)） |
| `owned_agent_required`（403） | `owned_agent_required`（`project create`・`project assign`）、他は`not_authorized` | 元Sessionのownerが所有する、削除されていないagentだけを指定できる | 所有するagentを選ぶ。他のagentや人間は、権限のある人間の経路で追加する |
| `project_lead_required`（403） | `project_lead_required`（`project assign`）、他は`not_authorized` | 現在のProject LeadのSessionからだけ実行できる。Leadがいない場合は`Assign an active Project Lead before delegating work.` | Project LeadのSessionから実行する。Leadがいなければ先にLeadを決める |
| `project_lead_status_only`（403） | `not_authorized` | Project LeadがSessionから変えられるのはstatusの`active`・`completed`だけである | ほかの変更はProject adminに依頼する |
| `project_launch_owner_parent_membership_required` / `project_lead_relation_membership_required`（403） | `not_authorized` | 子Projectの作成やLead変更に必要なmembershipが足りない（`Add the parent Lead agent owner as a parent collaborator, then retry.`など） | `message`のmembershipを追加してから再実行する（[Leadを変更し、子Projectの成果を読む](/ja/docs/projects#leadを変更し子projectの成果を読む)） |

`ask_cancel_not_authorized`は[Ask・待機](#ask待機)にある。

## Project

| code（HTTP） | chatでの表示 | 意味 | 次の操作 |
|---|---|---|---|
| `PROJECT_NOT_FOUND`（404） | `project_not_found` | Projectがない、または見えない（`Project not found`） | `chat projects --status all`で名前を確かめる（[Projectや文書が読めない](/ja/docs/troubleshooting#projectや文書が読めない)） |
| `project_not_active`（404） | `project_not_active` | ProjectがIn progressでないため、中身が隠れている。何も削除されていない | Project adminにstatusを**In progress**へ戻してもらう（[statusと閲覧・実行の可否](/ja/docs/projects#statusと閲覧実行の可否)） |
| `AMBIGUOUS_PROJECT`（400） | `ambiguous_project` | 同じ名前のProjectが複数見える（`Multiple visible projects named '<name>'`） | `<team>/<project>`の形で指定する |
| `project_report_required_for_completion`（409） | `conflict` | REPORT.mdが不足していてDoneにできない（`Create or update REPORT.md, then retry completing this Project.`） | [REPORT不足でDoneにできない](/ja/docs/troubleshooting#report不足でdoneにできない)を読む |
| `active_child_projects_exist`（409） | `conflict` | activeな子ProjectがあるためArchiveできない | 子をDoneにする、付け替える、またはArchiveしてから再実行する（[Archiveを受け付けられない・完了しない](/ja/docs/troubleshooting#archiveを受け付けられない完了しない)） |
| `project_reparent_status_conflict`（409） | `conflict` | 付け替える子がplanning・activeでない、または新しい親がactiveでない | 子を開き直すか、activeな親を選ぶ |
| `project_relation_cycle`（409） | `conflict` | 自分の子孫を親にしようとした（`Choose a parent outside this Project's descendant chain.`） | 子孫の外のProjectを親に選ぶ（[引き継ぎBriefを渡して子を移す](/ja/docs/projects#引き継ぎbriefを渡して子を移す)） |
| `project_lead_membership_required`（409） | `conflict` | 現在のLeadを外す操作の前に、Leadを替える必要がある（`Change the Project Lead before ...`） | 先にLeadを変更してから、member削除やviewerへの変更をする |
| `project_launch_idempotency_conflict` / `project_reparent_idempotency_conflict`（409） | `conflict` | 同じnonceが別の内容の要求ですでに使われている | 内容が違う要求なら新しいnonceで送る。同じ要求の再送なら引数を元と揃える |
| `project_template_preview_changed`（409） | `conflict` | previewの後にテンプレートや準備したAgentが変わった | 新しいpreviewを確認してから開始し直す |
| `team_resource_protocol_mismatch`（409） | `conflict` | クライアントとserverでTeam共有リソース（Workflow revisionなど）の版が合わない | `aachat update`の後、人間に`aachat up`とdaemonの再起動を依頼する |

Archiveと削除は非同期で進み、途中の失敗はエラー応答ではなくProjectの処理状態に残る。WebUIの**Could not complete Archive** / **Deletion failed**に出る。

| code（HTTP） | chatでの表示 | 意味 | 次の操作 |
|---|---|---|---|
| `stop_unconfirmed`（処理状態） | — | 受付から300秒たってもSessionの停止を確認できない | 示されたSessionを確認してから**Retry**を選ぶ（[Archiveを受け付けられない・完了しない](/ja/docs/troubleshooting#archiveを受け付けられない完了しない)） |
| `run_cancel_failed`（処理状態） | — | Workflow Runを取り消せなかった | 示されたRunを確認してから**Retry**を選ぶ |
| `archive_retry_required`（処理状態） | — | Archiveの処理が内部で失敗した | **Retry**を選ぶ |
| `project_deletion_step_failed`（処理状態） | — | 削除の途中の段階が失敗した（`Project deletion failed in ... Retry after the dependency recovers.`） | 同じProjectの**Retry**から再開する（[Project削除が失敗した](/ja/docs/troubleshooting#project削除が失敗した)） |

## Session

| code（HTTP） | chatでの表示 | 意味 | 次の操作 |
|---|---|---|---|
| `SESSION_NOT_RUNNING`（409） | `session_not_running`（`edit`・`delete`では`message_mutation_failed`、`skill feedback`では`session_not_active`） | 対象のSessionが実行中でない（`Target session is not running. ...`） | `chat session read`で状態を読む。再開できる`stopped`・`failed`なら`--resume`を付けて送る（[Sessionが失敗した・途中で止まった](/ja/docs/troubleshooting#sessionが失敗した途中で止まった)） |
| `session_not_running`（409、小文字） | `session_not_running` | 成果報告などを、実行が受け付けられたturnの外から送った（`Session is not running with an execution-accepted turn`） | 実行中のturnの中で報告し直す。turnが終わった後は送れない |
| `stale_bootstrap_generation`（409） | `conflict` | 同じSessionの古いruntimeからの要求である（runtime再起動の後など） | `chat session read`で現在の状態を読む。古いprocessからの記録は受け付けられない |
| `AGENT_RUNTIME_OFFLINE`（409） | `agent_runtime_offline` | agentのruntimeが接続していない（``Agent runtime is offline. Start or reconnect `aachat up`, then retry.``） | 人間にそのagentの`aachat up`起動を依頼してから再実行する（[Sessionが起動しない](/ja/docs/troubleshooting#sessionが起動しない)） |
| `AGENT_RUNTIME_PROJECT_UNAVAILABLE`（409） | `agent_runtime_project_unavailable` | runtimeは接続しているが、そのProjectを受け取っていない | 人間に`aachat up`の再接続か、agentのProject membershipの更新を依頼する |
| `SESSION_COMMAND_UNDELIVERED`（409） | `session_command_undelivered` | 配送を確認できない、またはruntimeが指示を拒否した | `message`を読み、Sessionの履歴・状態・適用結果を確認する。必要なら接続を復旧し、未到達・未適用を確認できた操作だけ一度再送する。許可への回答は専用の復旧手順を使う（[runtimeへの配送](/ja/docs/troubleshooting#操作がruntimeへ届かない)） |
| `SESSION_PENDING_FOLLOW_UPS`（409） | `session_pending_follow_ups`（`session finish`）、他は`conflict` | 送信待ちのfollow-upがあるため、Sessionを終えられない。Sessionは動き続ける | このturnを終え、次のturnで処理してから`chat session finish`を再実行する |
| `workflow_session_managed`（409） | `workflow_session_managed`（`session finish`） | Workflow Step Sessionの終了はWorkflowが管理する | `session finish`を再実行しない。turnを通常どおり終え、Workflowの完了指示に従う（[Session Stepを完了する](/ja/docs/workflows#session-stepを完了する)） |
| `SESSION_ALREADY_STARTED`（409） | `conflict` | そのSessionはすでに最初のturnを受け付けている | 動いているSessionを開くか、新しいSessionを始める |
| `CONFLICT`（409、`existing_session_id`あり） | `conflict`（`existing_session_id`は表示されない） | 同じclient nonceが、別の内容の起動要求ですでに受け付けられている | `existing_session_id`のSessionを開く。別の仕事なら新しいnonceで起動する（[起動結果の受付](/ja/docs/sessions#起動結果の受付chat-session-run)） |
| `CONFLICT`（409、`This session is ready for its first run. ...`） | `conflict` | まだ一度も実行していないSessionへfollow-upを送った | Projectのcomposerから最初の実行を始める |
| `QUEUED_FOLLOW_UP_NOT_QUEUED` / `QUEUED_FOLLOW_UP_CHANGED`（409） | — | 編集しようとした送信待ちmessageが、もう待っていない、または別の場所で変わった | 会話とqueueを読み直してから操作する（[送信待ちのfollow-upを編集・削除・先に実行する](/ja/docs/sessions#送信待ちのfollow-upを編集削除先に実行する)） |

### live表示のcode

WebUIのlive表示の取得で返る。`chat`からは届かない。画面には`Live updates could not keep up.`や`Could not update the live view.`などの文が出る（[live表示とTool出力の保存](/ja/docs/sessions#live表示とtool出力の保存)）。

| code（HTTP） | chatでの表示 | 意味 | 次の操作 |
|---|---|---|---|
| `live_snapshot_busy`（429） | — | live表示の取得が混んでいる | **Retry**で読み直す |
| `live_snapshot_timeout`（504） | — | 取得が時間内に終わらなかった | **Retry**で読み直す |
| `stale_active_turn` / `live_snapshot_unavailable`（409） | — | 実行中のturnが変わった、またはlive表示を取れない | **Retry**で読み直す。古いruntimeなら[Desktop](/ja/docs/desktop#sessionにlive-view-is-unavailable-with-this-versionと出たとき)を読む |
| `live_snapshot_encode_failed`（500） | — | live表示を組み立てられなかった | **Retry**で読み直す。続く場合は報告する |

## 成果報告の項目code

`chat result report`は、項目ごとの結果を`data.items[]`に返す。失敗した項目は`status: error`で、`code`・`message`・`retryable`を持つ。1項目でも失敗すると、全体の`error.code`は`result_report_incomplete`になる（[報告の結果を読む](/ja/docs/code-delivery#報告の結果を読む)）。

| code（項目） | chatでの表示 | 意味 | 次の操作 |
|---|---|---|---|
| `project_required` | 同じ | 記録先のProjectを決められない。Sessionのturnが複数Projectにまたがる、または一つもない | その項目に`results[].project`か`--project <team>/<project>`を付けて送り直す |
| `result_project_conflict` | 同じ | 指定したProjectが、その成果のProjectと食い違う | 既存の成果と同じProjectを指定する |
| `invalid_ref` | 同じ | `ref`が解決できない、または存在しない | refの形と対象の存在を確かめる |
| `unsupported_ref` | 同じ | 成果として記録できない種類のrefである | 対応するrefに変える |
| `delivery_repository_mismatch` | 同じ | PR・branchのrepositoryがこのSessionのrepositoryでない（`<repo> is not a repository of this Session (accepted: ...)`） | `accepted`に出たrepositoryのPR・branchを報告する |
| `duplicate_target` / `duplicate_input` | 同じ | 同じ対象、または同じinputを一度の報告に重ねた。重なった項目はすべて拒否される | 一つにまとめて送り直す |
| `version_conflict` | 同じ | 読んだ後に成果が更新された。`current`に現在の値が付く | `current`を読み、新しい通常の更新として送る |
| `result_not_found` | 同じ | 除外などの対象にした成果がまだない | 先に成果を記録するか、対象を確かめる |
| `storage_unavailable` | 同じ | 成果の保存先が一時的に使えない（`retryable: true`） | `data.retry_file`を使って再送する |
| `invalid_report` | 同じ | 上のどれにも当たらない項目の誤り。`message`が理由を示す。廃止した`delivery`入力を含む項目もこれになる | `message`に従ってその項目だけを直す |

報告そのものが受け付けられない場合は、項目codeではなく全体のエラーになる。turnの外からは`session_not_running`、古いruntimeからはserverの`stale_bootstrap_generation`（`chat`では`conflict`。[Session](#session)）である。

## Ask・待機

| code（HTTP） | chatでの表示 | 意味 | 次の操作 |
|---|---|---|---|
| `invalid_ask`（422） | `invalid_argument` | Askの入力が不正である（`options must be empty or contain 2 to 5 values`、`Ask creation requires an active regular Project`など） | `message`に合わせて直す |
| `invalid_ask_assignee`（422） | `invalid_argument` | 担当者がactiveな人間のProject memberでない。HTTPの本文には候補の`candidates`が付く | Project memberの人間を担当者に選ぶ |
| `invalid_ask_filter` / `invalid_ask_wait`（422） | `invalid_argument` | 一覧の条件やcursor、待ち時間が不正である（`timeout_secs must be between 1 and 50`など） | 値を直す。cursorは直前の一覧の値を使う |
| `ask_nonce_reuse`（409） | `conflict` | 同じclient nonceが別の内容ですでに使われている | 別の要求なら新しいnonceで送る |
| `ask_answer_conflict`（409） | — | 回答時に送ったrevisionが最新でない。本文に最新のAsk（`latest_ask`）が付く | 最新のAskと回答を読んでから回答し直す（[Askへ回答したが続かない](/ja/docs/troubleshooting#askへ回答したが続かない)） |
| `ask_cancel_not_authorized`（403） | 同じ | Askを取り消せるのは作成者・担当者・Project adminだけである | そのいずれかに取り消しを依頼する |
| `ask_conflict`（409） | `conflict` | Askの状態と合わない操作である（`Ask is already cancelled`・`Answered Ask cannot be cancelled`・`Cancelled Ask cannot be answered`・`Source Session is terminal`・`Project is not active`） | Askの現在の状態を読んでから判断する |
| `ambiguous_id`（400） | 同じ | 短いIDが複数の対象に一致した（`` `<prefix>` matches ... Pass one full ID. ``） | `candidates`から完全なIDを選ぶ（[IDの指定](/ja/docs/cli#idの指定)） |
| `VALIDATION_ERROR`（400、`chat wait`） | `wait_targets_invalid` | 待機の対象が条件に合わない | `commands`の読取りで各IDを確かめ、正しい組み合わせを新しいclient nonceで作る（[待機（chat wait）](/ja/docs/cli#待機chat-wait)） |

## 文書・同期・Wiki

`aachat up`による文書・HTML・Databaseのmigration・Wikiの同期の失敗は、エラー応答としてではなく、各フォルダの`_errors.md`に出る。文書などは`sync write attempt API error <status> (<code>): <message>`、Wikiは`Wiki write failed (HTTP <status>, <code>): <message>`の形である。

| code（HTTP） | chatでの表示 | 意味 | 次の操作 |
|---|---|---|---|
| `sync_protocol_version_mismatch`（426） | `unexpected_response` | クライアントの版がserverと合わない。認証付きのGET以外の要求と、同期APIのすべての要求で検査される | `aachat update`を実行するか、WebUIを再読込する。古い手元のworkspaceは保全してから人間に`aachat up`の再起動を依頼する（[`aachat up`が起動失敗する・途中で止まる](/ja/docs/troubleshooting#aachat-up-が起動失敗する途中で止まる)） |
| `write_conflict`（409） | — | 手元の変更の元になった版が最新でない（`projected file row version mismatch`） | 最新版との照合結果を確かめて直す（[ローカル投影での編集競合](/ja/docs/shared-documents#ローカル投影での編集競合)） |
| `permission_denied`（403） | — | このSessionまたはagentはそのProjectへ書けない（read-only membership、Sessionの範囲外など）。`reason: session_closing`はSessionの終了処理中で、手元の変更は未保存のまま残る | `message`の条件を確かめる。`session_closing`なら終了処理の結果を確認し、未保存の変更は次のSessionで保存する |
| `project_unavailable`（404） | — | Projectがない、activeでない、またはTeamが使えない（`project is unavailable for projected file sync`） | Projectのstatusを確かめる（[Projectや文書が読めない](/ja/docs/troubleshooting#projectや文書が読めない)） |
| `invalid_path` / `invalid_content` / `invalid_operation`（400。大きすぎる内容は413） | — | path・内容・操作が規則に合わない。理由は`message`にある | `message`に従ってファイルを直して保存し直す。生成された`_errors.md`は編集しない（[Shared Documentsが同期されない](/ja/docs/troubleshooting#shared-documentsが同期されない)） |
| `storage_unavailable`（503） / `internal` | — | 保存先が一時的に使えない、またはserver内部の失敗 | 時間をおいて同期の再試行を待つ。続く場合は報告する |
| `wiki_conflict`（409） | — | 先に他の人がWikiを保存した（`The Wiki changed. Your draft is kept.`）。原稿は残る | WebUIの**Review changes**で差分を確かめ、解消稿を保存する（[Team Wiki](/ja/docs/team-wiki)） |
| `wiki_reference_conflict`（409） | — | 本文のWikiリンク先が移動・削除され、参照の確認が必要である | 参照先を確かめて解消稿を保存する |

## Media・添付

### 送信時のエラー

Sessionへの指示やmessageに添付・Project Mediaを付けたとき、問題があると`INVALID_ATTACHMENT`（400）が返る。`chat`では`invalid_argument`になる（`chat session run --attach`などのupload自体の失敗は`attachment_upload_failed`）。

| `message` | 意味 | 次の操作 |
|---|---|---|
| `a message can include at most 10 attachments` | 1つのmessageの添付は10件までである | 件数を減らす |
| `message attachments exceed the 250 MiB total limit` | 添付の合計が250 MiBを超えた | 小さくするか、分けて送る |
| `the same attachment cannot be included more than once` | 同じ添付を二重に付けた | 重複を外す |
| `attachment is unavailable; attach the file again` | 添付が期限切れ、別Project・別送信者のもの、または未完了である | ファイルを添付し直す |
| `Project Media is unavailable; remove it and retry` | 付けたProject Mediaがreadyでない、または別Projectのものである | 外して再送する。Mediaがreadyになってから付け直す |
| `attachment metadata changed before the turn was accepted; retry the send` ほか`message attachment ...` | 送信中に添付の情報が変わった、または形が不正である | もう一度送信する |

ほかに、`message`の先頭にcodeが付く失敗がある。

| code（HTTP） | chatでの表示 | 意味 | 次の操作 |
|---|---|---|---|
| `media_limit_exceeded: choose a file between 1 and <max> bytes`（413） | `attachment_upload_failed`（`chat`の添付） | 宣言したファイルサイズが0か、形式ごとの上限を超える | 上限内のファイルにする（[対応形式と上限](/ja/docs/media#対応形式と上限)） |
| `project_media_quota_exceeded: ...`（413） | — | Project Mediaの合計が20 GiBを超える | 使わないMediaを削除するか、未完了のuploadを取り消してから再実行する |
| `media_in_use: ...`（409） | `media_delete_conflict` | 現在のShared DocumentやProject HTMLがそのMediaを参照しているため削除できない | 参照を外してから削除する（[削除](/ja/docs/media#削除)） |
| `attachment_upload_expired: ...`（409） | `attachment_upload_failed` | 添付のuploadの期限が切れた | 新しく添付し直す |

### Mediaと添付の失敗状態

Project Mediaが`failed`になると、Mediaの`error.code`と`error.message`に理由が残る。Sessionへの添付の失敗も同じcodeで示される。WebUIのMediaタブや添付の表示で読む。

| code | chatでの表示 | 意味 | 次の操作 |
|---|---|---|---|
| `media_upload_failed` | — | uploadされたサイズが宣言と一致しない | ファイルをもう一度追加する |
| `media_type_not_supported` | — | 対応していない形式である | 画像（PNG・JPEG・WebP・GIF）、MP4、PDFにする |
| `media_invalid` | — | 壊れている、途中で切れている、または暗号化PDFで、検証できない | 正しいファイル・暗号化していないPDFに置き換える |
| `media_limit_exceeded` | — | サイズ・寸法・ページ数・長さなどの上限を超える | 上限内のファイルに置き換える（[容量・実行条件](/ja/docs/limits#添付とproject-media)） |
| `media_kind_mismatch` | — | 中身が宣言した種類と合わない | ファイルを置き換える。拡張子だけを変えても形式は変わらない |
| `media_processing_failed` | — | 動画を処理できなかった | ファイルを置き換えて再実行する |
| `media_upload_expired` | — | uploadが期限内に完了しなかった | Mediaからもう一度追加する |

WebUIでの追加の準備に失敗すると、`upload_errors[]`に`upload_temporarily_unavailable`（一時的。もう一度uploadする）、`upload_preparation_failed`（権限を確かめてからuploadし直す）、`upload_not_prepared`（準備が終わらなかった。もう一度uploadする）が返る。Sessionで同Projectのready一覧にないMediaを読もうとしたときの`media_unavailable`は[`chat` CLIのエラーコード](#機能ごとのcode)を読む。

## Project HTML

Project HTMLのbuildの失敗は、codeではなく説明文でHTMLタブの診断に出る。文の形で探す。

| 説明文 | 意味 | 次の操作 |
|---|---|---|
| `Project HTML build failed in <path>. ...` / `... at reference '<ref>'. ...` | そのファイル、またはMediaへの参照の書き方が不正である | 参照をcanonical formに直して同期し直す（[同じProjectのMediaを参照する](/ja/docs/html#同じprojectのmediaを参照する)） |
| `Project HTML references Media that is missing or not ready: ...` | 参照したMediaがない、またはまだreadyでない | Mediaがreadyになれば自動で作り直される。ない・失敗・削除済みなら置き換えを公開し、参照を直す |
| `Project HTML build failed because <path> is <size> bytes after Media references are rewritten; ...` / `... the rewritten delivery is <size> bytes; ...` | 参照の書き換え後に、1ファイルまたは全体が上限を超えた | ファイルや繰り返しの参照を減らして同期し直す（[HTMLとShared Documents](/ja/docs/limits#htmlとshared-documents)） |

共有とpreviewの操作では、次の文が返る。

| code（HTTP） | chatでの表示 | 意味 | 次の操作 |
|---|---|---|---|
| `CONFLICT`（409、`Project HTML delivery build is not ready. ...`） | `conflict` | 最新buildが使えないため、共有やpreviewができない | HTMLタブの最新buildの診断を解消してから再実行する |
| `CONFLICT`（409、`This project already has a public HTML link. ...`） | `conflict` | public linkはProjectに一つだけである | 既存のlinkを更新またはresetする（[共有する](/ja/docs/html#共有する--share-html外部向けpublic-url)） |
| `CONFLICT`（409、`Extend the expired public HTML link before resetting its URL.`） | `conflict` | 期限切れのlinkはURLをresetできない | 先に期限を延ばす |
| `VALIDATION_ERROR`（400、`expires_in_days must be between 1 and 30` など） | `invalid_argument` | 期限やpasswordの指定が不正、または何も変更していない | 1〜30日の期限かpasswordを指定する |
| `STORAGE_UNAVAILABLE`（503、`Project HTML storage is temporarily unavailable. ...`） | `server_error` | HTMLの保存先が一時的に使えない | 時間をおいて再実行する |

## Project Database

`chat db`では、`DATABASE_SQL_EXECUTION_FAILED`と`DATABASE_RESULT_TOO_LARGE`だけが小文字の同名codeになる。ほかはHTTP statusで決まる共通のcodeになり、次の操作は`hint`に入る。

| code（HTTP） | chatでの表示 | 意味 | 次の操作 |
|---|---|---|---|
| `DATABASE_NOT_INITIALIZED`（409） | `conflict` | まだmigrationが一つもない | 最初の`db/migrations/<id>.sql`を作り、`chat db migrate <file>`を実行する（[tableを作り成果を1件保存する](/ja/docs/database#tableを作り成果を1件保存するsession内)） |
| `DATABASE_PREPARING` / `DATABASE_OVERLOADED`（503） | `server_error` | Databaseの準備中、または混んでいる | 少し待って同じコマンドを再実行する |
| `DATABASE_RECONCILING`（503） | `server_error` | schemaの状態を照合中である。SELECTとDMLは続けられる | 照合が終わるのを待って、schemaやmigrateを再実行する |
| `PROJECT_DATABASE_SOURCE_CONFLICT`（409） | `conflict` | serverにそのmigrationファイルがまだない。同期が終わっていないか、同期で拒否された | `db/_errors.md`にそのmigrationがあれば理由を直して保存する。なければ同期を待つ。その後同じmigrateを再実行する |
| `PROJECT_DATABASE_FROZEN`（409） | `conflict` | ProjectがArchivedのため使えない | Projectをarchive解除してから使う |
| `DATABASE_SQL_INVALID` / `DATABASE_VALUE_UNSUPPORTED`（422） | `invalid_argument` | SQLが規則に合わない、または結果に扱えない値がある（BLOBは`hex()`で変換する） | SQLか位置指定の文字列parameterを直す（[queryとmigrationのSQL規則は異なる](/ja/docs/database#queryとmigrationのsql規則は異なる)） |
| `DATABASE_SQL_EXECUTION_FAILED`（422） | `database_sql_execution_failed` | SQLまたは渡した値がDatabaseに拒否された | 制約と現在の行を確かめ、SQLか値を直す |
| `DATABASE_SQL_RESOURCE_LIMIT`（422） | `invalid_argument` | SQLの実行コストが上限を超えた | 文・parameter数・結果を小さくする |
| `DATABASE_RESULT_TOO_LARGE`（413） | `database_result_too_large` | 結果が大きすぎる | 列や行を減らす（[Project Database](/ja/docs/limits#project-database)） |
| `MIGRATION_ID_CONFLICT`（409） | `conflict` | 同じmigration IDが、違う内容ですでに適用済みである | 元の内容に戻すか、新しいmigration IDで作る |
| `MIGRATION_VERSION_CONFLICT`（409） | `conflict` | migrationの親versionが古い | `chat db schema`を読み、現在のversionから作り直す |
| `OPERATION_OUTCOME_UNKNOWN`（409） | `conflict` | 書込みが反映されたかわからない | 同じ書込みを送らない。SELECTで現在の値を確かめる（[書き込みを重複させずに復旧する](/ja/docs/database#書き込みを重複させずに復旧する)） |
| `DATABASE_SCHEMA_CHANGED`（409） | — | WebUIで見ている間にschemaが変わった | Database画面を読み直してtableを選び直す |
| `DATABASE_PROVISIONING_CONFLICT`（500） | `server_error` | Databaseの準備で不明な状態が見つかった。運用側の修復が必要 | SQLや資格情報を含めずに報告する |

## Workflow

### 定義と入力の検証

Workflow系のコマンドでは、下のcodeが小文字のまま`chat`に出る。終了コードは2で、`invalid_output`と`rendered_prompt_too_large`だけは1である。位置は`got`、理由は`message`にある。

| code（HTTP） | chatでの表示 | 意味 | 次の操作 |
|---|---|---|---|
| `invalid_workflow_yaml` / `invalid_bundle_path` / `cyclic_dependency` / `unknown_step_reference` / `invalid_prompt_variable` / `missing_completion_instruction` / `invalid_completion_instruction`（422。`client_nonce`の誤りは400） | 同じ | Workflow定義・Bundleの検証エラー | `message`の箇所を直して検証し直す（[定義のfield](/ja/docs/workflow-reference#定義のfield)） |
| `invalid_input` / `invalid_output`（422。128 KiBを超える入力は413） | 同じ | 入力・出力がschemaに合わない | schemaに合わせて値を直す（[入力・出力schemaの対応範囲](/ja/docs/workflow-reference#入力出力schemaの対応範囲)） |
| `bundle_too_large` / `rendered_prompt_too_large`（413） | 同じ | Bundle、または展開後のpromptが上限を超えた | 小さくする（[上限と超過時の対応](/ja/docs/workflow-reference#上限と超過時の対応)） |

### Draft・公開・Run・完了

| code（HTTP） | chatでの表示 | 意味 | 次の操作 |
|---|---|---|---|
| `draft_version_conflict`（409） | 同じ | 読んだ後にDraftが変わった | 最新のDraftを読み直してから変更し直す |
| `workflow_unpublished`（409） | 同じ | Workflowが公開されていない | Draftを公開してから再実行する（[検証・試行・公開](/ja/docs/workflows#検証試行公開)） |
| `workflow_archived`（409） | `conflict` | Workflowがarchiveされている | `chat workflow restore`で戻してから、編集・公開・Runの開始をする（[アーカイブと復元](/ja/docs/workflows#アーカイブと復元)） |
| `workflow_revision_changed`（409） | `conflict` | 読んだ後にrevisionが変わった | revisionを読み直す |
| `invalid_run_state`（409） | 同じ | Runの状態がその操作を受け付けない（取消中、retryできないStep、取消できない状態、子Runの直接取消、古い形式の読取専用の履歴など）。理由は`message`にある | Runの状態を読む。古いRunなら新しいRunを始める（[状態別の次の操作](/ja/docs/workflows#状態別の次の操作)） |
| `completion_already_submitted`（409） | 同じ | そのStepはすでに別の完了を受け付けている | Run詳細で受け付けた完了を確かめる |
| `completion_session_mismatch`（409。Sessionが違うときは403） | 同じ（403では`not_authorized`） | 完了を送ったSessionが、担当のWorkflow Sessionでない、またはすでに終了処理に入っている | 担当のWorkflow Sessionの中で送る。終了済みならRun詳細を読む |
| `workflow_completion_not_ready`（409） | `conflict` | まだ完了を送る段階でない（`Finish the task messages first. ...`） | 作業を続け、Workflowが完了の指示を送ってから完了を送る |
| `workflow_access_revoked`（409） | 同じ | Stepのagentが、そのProjectのactiveなcollaboratorでない | agentをcollaboratorに戻してから、そのStepをretryする |
| `workflow_not_found` / `workflow_run_not_found`（404） | 同じ | Workflow、またはRunが見つからない | `chat workflow list`や現在のProjectのRun IDで指定し直す |
| `version_unavailable`（404） | `project_not_found` | 指定したrevision、またはRunの定義を読めない | revisionを指定し直す。Runなら現在の公開版から新しいRunを始める |

### Stepの失敗code

失敗したStepの`error.code`と`error.message`に残る。Run詳細や`chat workflow status`で読む（[Runを読み、復旧する](/ja/docs/workflows#runを読み復旧する)）。Sessionが起動の準備中に失敗した場合の`config_not_offered`などは[Sessionの失敗と起動時のcode](#sessionの失敗と起動時のcode)を読む。

| code | chatでの表示 | 意味 | 次の操作 |
|---|---|---|---|
| `agent_reported_failure` | 同じ | agentが失敗として完了を送った | Sessionの記録で理由を読み、原因を直してからretryする |
| `completion_missing` | 同じ | Sessionが完了を送らずに止まった | Sessionを読み、retryする |
| `session_failed` | 同じ | Step Sessionが失敗した | Sessionのエラーを読んで原因を直し、retryする |
| `workflow_session_rejected` | 同じ | Step Sessionの作成が拒否された。理由は`message`にある | `message`の原因を直してからretryする |
| `workflow_access_revoked` | 同じ | 実行中に、Stepの実行に必要な権限が失われた | 権限を戻してからretryする |
| `workflow_decision_cancelled` | 同じ | 人間の判断（Decision）のAskが取り消された | retryして新しいAskを作る |
| `workflow_completion_limit_exceeded` | 同じ | 子Workflowの出力が完了の上限を超えた | 大きな成果はProjectに保存して参照だけを返すように子を直して公開し、親を新しいRunで始める |

## Trigger・Webhook

| code（HTTP） | chatでの表示 | 意味 | 次の操作 |
|---|---|---|---|
| `time_trigger_request_conflict`（409） | 同じ（`trigger create`） | 同じ`request_id`が別の内容の作成要求ですでに使われている | `chat trigger list`で照合する。別の作成なら新しいrequest IDで送る |
| `time_trigger_request_deleted`（409） | 同じ（`trigger create`） | その要求で作ったTriggerが削除済みで、作り直されなかった | 必要なら新しいrequest IDで作る |
| `CONFLICT`（409、`Trigger changed or is dispatching. Refresh and retry.`） | `time_trigger_changed` | 読んだ後にTriggerが変わった、または起動中である | 最新の`state_version`を読み直して判断し直す（[競合、pause、成否不明から復旧する](/ja/docs/triggers#競合pause成否不明から復旧する)） |
| `NOT_FOUND`（404、Trigger IDを指定するコマンド） | `time_trigger_not_found` | そのProjectにTriggerがない | `chat trigger list --project <project>`でIDを確かめる |
| `CONFLICT`ほか409（Trigger IDを指定するコマンド、上の文以外） | `time_trigger_conflict` | Triggerの現在の状態や権限と衝突した | `commands`の`chat trigger show`で状態と理由を読み直してから操作を選ぶ |
| `invalid_input`（422、Webhook） | — | Webhook要求のJSON・Content-Type・field・metadata・promptが不正である | 要求を直して送る（[応答と再送](/ja/docs/triggers#応答と再送)） |
| `VALIDATION_ERROR`（413、Webhook） | — | 本文が256 KiBを超えた（`Webhook body exceeds 256 KiB`） | 本文を小さくする |
| `RATE_LIMITED`（429、Webhook） | — | 受付の上限に達した（`Webhook capacity reached; retry with the same idempotency_key`）。`Retry-After: 60`が付く | 60秒待ち、同じidempotency keyで再送する |

Triggerが`paused`のときは`pause_reason`が理由を示す。値は`manual`・`project_inactive`・`permission_revoked`・`target_unavailable`・`input_contract_invalid`・`workflow_archived`で、それぞれの復旧は[競合、pause、成否不明から復旧する](/ja/docs/triggers#競合pause成否不明から復旧する)にある。

起動の記録（occurrence）は`reason`を持つことがある。`previous_run_active`（前回の仕事が動いているためskip）、`superseded_during_downtime`（停止中に過ぎた予定をまとめてskip）、`previous_run_superseded`（前回の仕事を置き換えて受付）である。`failed`のoccurrenceの`reason`には、pauseした理由の説明文が入る。

## メッセージ・宛先

| code（HTTP） | chatでの表示 | 意味 | 次の操作 |
|---|---|---|---|
| `REPLY_TARGET_NOT_FOUND`（400） | `reply_target_not_found` | 返信先のmessageがない | `chat read <project>`で存在するseqを選ぶ |
| `INVALID_REPLY_TARGET`（400） | `invalid_reply_target` | 返信先がroot messageでない、または別Projectのものである | 同じProjectのroot messageを選ぶ |
| `MESSAGE_NOT_FOUND`（404） | `thread_message_not_found`（`thread`）、`post_type_message_not_found`（`post-type update`）、`message_mutation_failed`（編集・削除） | messageがない | `chat read <project>`でseqを選び直す |
| `MESSAGE_NOT_ROOT` / `MESSAGE_DELETED`（400） | `post_type_requires_root_message` / `post_type_message_deleted`（`post-type update`）、編集・削除では`message_mutation_failed` | 返信にはpost typeがない、または削除済みのmessageは変更できない | root messageや削除されていないmessageを選ぶ |
| `MESSAGE_POST_TYPE_FORBIDDEN`（403） / `INVALID_MESSAGE_POST_TYPE`（400） | `message_post_type_forbidden` / `invalid_message_post_type` | post typeを変える権限がない、または値が不正である | 書けるProjectで、対応する値を指定する |
| `USER_NOT_FOUND` / `AMBIGUOUS_USER`（400） | `user_not_found` / `ambiguous_user` | 名前に一致するmemberがいない、または複数いる。agentは`<agent>.<owner>`の形である | memberの正確な名前で指定する |

## Secrets（Tools > Secrets）

WebUIの**Tools > Secrets**の操作は、本文が`{"code": ...}`だけの応答を返す。説明文は付かない。値の保存や使用許可は、選んだComputerで動くaachatが行う。`chat`からは使わない（[Environment](/ja/docs/environment)）。

| code（HTTP） | chatでの表示 | 意味 | 次の操作 |
|---|---|---|---|
| `invalid_request`（400） | — | 要求の形が不正である | 画面を読み込み直して操作し直す |
| `too_large`（413） | — | 要求や値が大きすぎる | 値を小さくする |
| `not_found` / `owner_mismatch`（404） | — | 対象のComputerやAgentが見つからない、またはそのComputerのSecrets設定が別のownerのものである | 自分が接続しているComputerを選ぶ |
| `busy`（409） | — | 同じComputerで同じ種類の操作が進行中である | 終わるのを待って再実行する |
| `conflict`（409） | — | 操作中に手元の設定や使用許可が変わった | **Refresh**で読み直してから操作する |
| `unavailable`（503） | — | Computerが接続していない、または一つに決まらない | そのComputerで`aachat up`を起動し、**Refresh**する |
| `unsupported`（503） | — | そのComputerのaachatが古く、この操作に対応していない | そのComputerで`aachat update`を実行する |
| `local_setup_required`（503） | — | 旧形式のlocal設定が残っている | 認証済みの人間が端末で`aachat env adopt`を実行する（[旧local設定を採用する](/ja/docs/environment#旧local設定を採用する)） |
| `timeout`（504） | — | 40秒以内に終わらなかった | 状態を**Refresh**で確かめてから再実行する |
| `invalid_data` / `already_exists` / `permission_denied` / `cancelled` / `unknown`（400） | — | 手元の設定・Keychain・`.env`を読めない、すでに項目がある、OSの許可がない、取り消された、または分類できない失敗 | 対象Computerのファイル権限やKeychainの状態を確かめて**Refresh**する（[要求の確認と反映時点](/ja/docs/environment#要求の確認と反映時点)） |

## Skill

| code（HTTP） | chatでの表示 | 意味 | 次の操作 |
|---|---|---|---|
| `skill_not_found` / `ambiguous_skill` | 同じ（`skill feedback`） | feedbackの対象skillがない、または同名が複数ある。feedbackは保存されていない | `candidates`から正確な名前を選ぶ。同名なら`--source`を付ける |
| `skill_source_authorization_required`（403） | — | Skillのrepositoryを読むGitHub接続がない、または失効した | **Connect repository**で接続し直す（[Skill Ledger](/ja/docs/skills#skill-ledger)） |
| `skill_source_changed` / `skill_source_revision_conflict`（409） | — | 開いた後にsourceや版が変わった | 一覧から開き直す |
| `skill_source_file_missing`（404） / `skill_source_ref_missing`（502） | — | ファイル、またはbranchなどの参照が見つからない | branchとファイルの場所を確かめ、一覧から開き直す |
| `skill_source_rate_limited`（429） / `skill_source_timeout`（504） / `skill_source_fetch_failed`（502） | — | repositoryの取得が制限された、時間内に終わらなかった、または失敗した | 時間をおいて**Retry**する |
| `skill_source_limit_exceeded`（413） | — | 取得する内容が上限を超えた | Skillのファイルを小さくする |

## GitHub連携

GitHub APIの失敗は、GitHubのstatusに応じて読み替えられる。401・403・404・429はaachatの`UNAUTHORIZED`・`FORBIDDEN`・`NOT_FOUND`・`RATE_LIMITED`になり、`message`が`GitHub authentication failed.`・`GitHub access denied.`・`GitHub resource not found.`・`GitHub API rate limit exceeded. Please try again later.`で始まる。それ以外は`GITHUB_ERROR`（502）になる。

`message`がGitHubで始まる`UNAUTHORIZED`は、aachatのサインインではなくGitHubの認証の問題である。`chat`ではどちらも`token_required`になるので、`message`で区別する。

| code（HTTP） | chatでの表示 | 意味 | 次の操作 |
|---|---|---|---|
| `UNAUTHORIZED`（401、`GitHub authentication failed. ...`） | `token_required` | GitHubの認証が失敗した | 人間にGitHubの再認証を依頼する（[認証で失敗する](/ja/docs/troubleshooting#認証で失敗する)） |
| `FORBIDDEN`（403、`GitHub access denied. ...`や``... requires the `<scope>` GitHub permission. Please re-authorize.``） | `not_authorized` | GitHubの権限やscopeが足りない | 必要な権限で再認証する。repositoryの接続なら[GitHub repositoryを接続できない](/ja/docs/troubleshooting#github-repositoryを接続できない)、cloneなら[Discoverのcloneが失敗する](/ja/docs/troubleshooting#discoverのcloneが失敗する)を読む |
| `RATE_LIMITED`（429、`GitHub API rate limit exceeded. ...`） | `network_error` | GitHub APIの利用制限に達した | 時間をおいて再実行する |
| `GITHUB_ERROR`（502） | `server_error` | GitHub APIが想定外の応答を返した（`GitHub API returned an unexpected error (<status>). ...`） | 時間をおいて再実行する |

## 外部AI接続（OAuth）

Connected apps（リモートMCP）のOAuthの入口は、OAuthの標準の形`{"error": "<code>"}`で失敗を返す。codeは`invalid_request`・`invalid_client`（401）・`invalid_client_metadata`・`invalid_grant`・`invalid_scope`・`unsupported_grant_type`・`temporarily_unavailable`・`server_error`（503）である。これは外部AIのクライアントが扱うもので、利用者は外部AIの接続をやり直す（[Connected apps](/ja/docs/webui#connected-apps)）。

## `aachat` CLIのエラーコード

`aachat`の通常コマンドは、失敗するとstdoutに一つのJSONを返す。形は`{"ok": false, "error": {"code": ..., "message": ..., "field"?, "expected"?}, "data"?, "warnings"?, "next_actions"?}`である。まず`next_actions`を読み、次に`message`を読む。`data`は部分結果や`change.state`（`not_applied`・`applied`・`unknown`）があるときだけ付く。

終了コードは、`invalid_argument`・`missing_argument`・`conflicting_arguments`が2、それ以外の失敗は1である。`aachat up`・対話型の`aachat support`・`aachat manage-agent`・`aachat env --interactive`・`aachat doc check --hook`はJSONを返さない（[出力形式](/ja/docs/cli#出力形式)）。

serverが返したcode（`FORBIDDEN`・`AGENT_RUNTIME_OFFLINE`など）は、`aachat`では下表の少数のcodeに読み替えられる。serverの説明文は`message`に残る。元のserver codeで探すときは、server APIコードの節を読む。

| code | 意味 | 次の操作 |
|---|---|---|
| `auth_required` | aachatの認証が使えない。サインインの期限切れや、serverが認証を拒否した（HTTP 401）場合に出る | `aachat auth status`を読む。`gh`が認証済みなら`aachat auth login`で更新できる。GitHubへのログインが必要なら人間に`gh auth login`を依頼する（[認証で失敗する](/ja/docs/troubleshooting#認証で失敗する)） |
| `authentication_required` | `aachat auth login`がGitHub CLIの認証tokenを取得できなかった | 人間に`gh auth login`を依頼し、`aachat auth login`を再実行する |
| `team_required` | Teamを決められない。接続済みrepoの外で`--team`がない、または見えるTeamが一つもない | `--team <slug>`を渡すか、接続済みrepoの中で実行する。`aachat status`で接続を確認する |
| `ambiguous_team` | 候補のTeamが複数ある | `--team <slug>`を渡す |
| `team_not_found` | repoの接続先Teamが、今のアカウントから見えない | Teamのownerにアクセスを依頼し、`aachat status`で確認する |
| `repo_not_connected` | 接続済みrepoが必要な操作を、`aachat/README.md`がないrepoやrepoの外で実行した | 接続済みrepoのrootで実行する。未接続なら人間に`aachat init`を依頼する |
| `connection_invalid` | repoの接続情報（`aachat/README.md`の内容や版）が不正で読めない | `aachat status`の`connection.reason`と`next_actions`に従って直し、`aachat init`を実行する |
| `permission_denied` | 操作の権限がない（HTTP 403など）。`--output`の書込み先の権限不足でも出る | Team・Projectのownerに権限を依頼する。`--output`なら書込み先を変える |
| `admin_required` | Project adminの権限が必要な操作である | Project adminに操作か権限付与を依頼する |
| `collaborator_required` | Projectへの書込み権限（collaboratorまたはadmin）が必要である | 書込み権限のあるmemberに追加を依頼するか、書けるProjectを選ぶ |
| `project_out_of_scope` | 今の資格情報で扱える範囲の外のProjectを指定した | 対象を扱えるProjectを指定し直す |
| `cross_project_read_only` | 他のProjectは読むだけで、変更できない | 自分のProjectで報告し、そのProjectの人間かLeadに任せる |
| `project_not_found` | Projectが見つからない。存在しないか、見えない | `aachat project list`などで名前とTeamを確認する（[Projectや文書が読めない](/ja/docs/troubleshooting#projectや文書が読めない)） |
| `session_not_found` | Sessionが見つからない | `aachat session list --agent <name>`でIDを確認する |
| `agent_not_found` | agentが見つからない。Projectのmemberでないagentを指定した場合も出る | agent名を確認し、必要ならProjectへ追加する |
| `blueprint_not_found` | 取得元のrepositoryやblueprintが見つからない・読めない | 指定した取得元と、GitHubでの閲覧権限を確認する |
| `session_not_running` | 対象のSessionが実行中でない | `aachat session read <id> --project <project>`で状態を読む。再開は[Sessionが失敗した・途中で止まった](/ja/docs/troubleshooting#sessionが失敗した途中で止まった)を読む |
| `not_found` | 指定した文書path・保存済みの本文・選んだmessageなどが存在しない | `message`と`field`を読み、一覧から指定し直す |
| `conflict` | 現在の状態と衝突した（HTTP 409など）。Archiveを妨げるProjectやSessionがある場合も出る | 状態を読み直し、`data`に示された原因を解消してから再実行する |
| `invalid_argument` | 引数・値が不正。Agent Session内で人間専用の`aachat`操作を実行した場合も出る | `message`・`field`・`expected`に合わせて直す。Session内なら`next_actions`の`chat`コマンドを使う（[出力形式](/ja/docs/cli#出力形式)） |
| `missing_argument` | 必須の引数やsubcommandがない | `aachat <command> --help`で必要な引数を確認する |
| `conflicting_arguments` | 同時に使えない引数を渡した | どちらか一方だけを渡す |
| `prerequisite_missing` | 前提が欠けている。必要なtool（`npx`など）がPATHにない、agentのruntimeが未接続でSessionを始められない、serverとsync protocolの版が合わない、などで出る | `message`で原因を区別する。toolを入れる、人間に`aachat up`を依頼する、`aachat update`を実行する、のいずれかを行う |
| `interactive_required` | 端末（TTY）が必要な操作を非対話で実行した。`aachat skills add`で`--skill`を指定していない場合も出る | 人間に端末で実行してもらう。`skills add`なら`--skill <name>`を指定する |
| `confirmation_required` | 確認が必要な操作に、確認の指定がない（`--yes`がない削除、未完了Runがある非対話Archiveでの`--cancel-runs`なし） | 人間の承認を得てから、`--yes`または`--cancel-runs`を付けて再実行する。何も変わっていない（[Archiveを受け付けられない・完了しない](/ja/docs/troubleshooting#archiveを受け付けられない完了しない)） |
| `content_changed` | `--full`で続きを読む間に、本文が変わった | `--offset 0`から読み直す |
| `already_exists` / `io_error` | `--output`の書込みに失敗した。前者は同名ファイルが既にある | 新しいpathを指定する。既存ファイルは上書きしない |
| `capacity` | 空き容量が足りずに書込みが失敗した、または`aachat status`の容量検査を時間内に片付けられなかった | `aachat doctor`で容量と保持workspaceを確認する（[空き容量不足でSessionが始まらない](/ja/docs/troubleshooting#空き容量不足でsessionが始まらない)） |
| `network_error` | serverへ接続できない。HTTP 429（送信が多すぎる）もこのcodeになる | 通信を確認し、時間をおいて再実行する。変更操作なら、再実行の前に最初の操作が受け付けられたかを確認する |
| `server_error` | serverが5xxを返した | 時間をおいて再実行する。続く場合は`aachat report`で報告する |
| `internal_error` | 上のどれにも当てはまらない失敗。ローカルのファイル・Gitの失敗や、想定外の応答で出る | `message`を読み、`aachat support`へ`code`と`message`を渡す |

## `chat` CLI（Session内）のエラーコード

Session内の`chat`は、失敗するとstdoutに`{"ok": false, "error": {"code": ..., "message": ..., ...}, "data"?: {...}}`を一つ返す。`error`には、あれば`command`・`project`・`name`・`field`・`got`・`expected`・`candidates`・`available_agents`・`commands`・`reply_to`・`hint`が付く。`commands`は次に実行できるcommand locatorの配列である。

`message`は、serverの説明文があればその文、なければ次の操作の案内である。serverの説明文が`message`に入ったときだけ、案内が`hint`に分かれて付く。

終了コードは、`invalid_argument`・`missing_argument`・`conflicting_arguments`と、Workflowの検証エラー（`invalid_input`・`invalid_workflow_yaml`・`invalid_bundle_path`・`bundle_too_large`・`cyclic_dependency`・`unknown_step_reference`・`invalid_prompt_variable`・`missing_completion_instruction`・`invalid_completion_instruction`）が2、それ以外は1である。

`chat`はserverのcodeを小文字のcodeへ読み替える。たとえばserverの`AGENT_RUNTIME_OFFLINE`は`agent_runtime_offline`、`FORBIDDEN`は`not_authorized`になる。

### 共通のcode

| code | 意味 | 次の操作 |
|---|---|---|
| `session_required` | `AA_SESSION_ID`がない環境で、Session専用のコマンドを実行した | aachat Sessionの中で実行する。Session外では`aachat`を使う |
| `token_required` | agentのtokenがない（`AA_TOKEN_FILE`・`AA_TOKEN`が未設定）、またはserverがtokenを拒否した（HTTP 401） | `aachat up`が起動したSessionの中で実行する。続く場合は人間に`aachat up`の状態確認を依頼する |
| `invalid_argument` | 引数・値が不正。入力ファイルやstdinが読めない、`AA_SESSION_ID`がUUIDでない、serverが入力を拒否した場合も出る | `field`・`got`・`expected`・`message`に合わせて直す |
| `missing_argument` | 必須の引数やsubcommandがない | `chat <command> --help`で確認する |
| `conflicting_arguments` | 同時に使えない引数を渡した | どちらか一方だけを渡す |
| `not_authorized` | 権限がない（HTTP 403） | 現在のSessionのtokenで実行しているかを確認し、Project memberに権限を依頼する |
| `admin_required` | Project adminの権限が必要である | Project adminに操作か権限付与を依頼する |
| `collaborator_required` | Projectへの書込み権限（collaboratorまたはadmin）が必要である | 書込み権限のあるmemberに追加を依頼するか、書けるProjectを選ぶ |
| `ask_cancel_not_authorized` | Askを取り消せるのは作成者・担当者・Project adminだけである | そのいずれかに取り消しを依頼する |
| `project_not_found` | Projectが存在しないか、このagentから読めない。二つは区別されない | `chat projects --status all`で名前を確認する（[Projectや文書が読めない](/ja/docs/troubleshooting#projectや文書が読めない)） |
| `project_not_active` | ProjectがIn progress（`active`）でない | Projectのstatusを In progress にするか、Project adminに依頼する（[Sessionが起動しない](/ja/docs/troubleshooting#sessionが起動しない)） |
| `project_out_of_scope` | 現在のSessionが扱うProjectの外である | 対象を扱うProjectを選ぶか、そのProjectを扱うSessionを始める |
| `cross_project_read_only` | 他のProjectは読むだけで、変更できない | 自分のProjectで報告し、人間かそのProjectのLeadに任せる |
| `session_not_found` / `ask_not_found` | 指定したProjectに、一致するSession・Askがない | `commands`の一覧でIDを確認するか、別の`--project`を選ぶ |
| `session_not_running` | 対象のSessionが実行中でない | `chat session read`で状態を読む。再開できる`stopped`・`failed`なら`--resume`を付けて送る（[Sessionが失敗した・途中で止まった](/ja/docs/troubleshooting#sessionが失敗した途中で止まった)） |
| `agent_not_found` / `ambiguous_agent` | 名前に一致するactiveなagentがない、または複数ある | `available_agents`・`candidates`から正確な名前を選ぶ |
| `agent_runtime_offline` | agentのruntimeが接続していない | 人間にそのagentの`aachat up`起動を依頼してから再実行する（[Sessionが起動しない](/ja/docs/troubleshooting#sessionが起動しない)） |
| `agent_runtime_project_unavailable` | runtimeは接続しているが、そのProjectを扱えない | 人間に`aachat up`の再接続か、agentのProject membershipの更新を依頼する |
| `session_command_undelivered` | 配送を確認できない、またはruntimeが指示を拒否した | `message`を読み、Sessionの履歴・状態・適用結果を確認する。必要なら接続を復旧し、未到達・未適用を確認できた操作だけ一度再送する。許可への回答は専用の復旧手順を使う（[runtimeへの配送](/ja/docs/troubleshooting#操作がruntimeへ届かない)） |
| `ambiguous_id` | 短いIDに一致する対象が複数ある | `candidates`から完全なIDを一つ選ぶ（[IDの指定](/ja/docs/cli#idの指定)） |
| `ambiguous_project` / `ambiguous_user` / `user_not_found` | Project名・user名が複数に一致する、または一致しない | `chat projects --status all`や、より具体的な名前で指定し直す |
| `reply_target_not_found` / `invalid_reply_target` / `thread_message_not_found` | 返信先やスレッドのmessageがない、またはroot messageでない | `chat read <project>`で存在するseqを選ぶ |
| `operation_outcome_unknown` | 変更の要求がserverで受け付けられたかわからない。送信後に応答が得られなかった場合や、HTTP 408・429・5xxで出る | 新しい要求を作らない。そのcommandの`message`と`hint`、上記のcommand別の回復案内に従う。`commands`は変更操作・読取りの場合も、省略される場合もある（[同じ要求の再送](/ja/docs/cli#同じ要求の再送)） |
| `conflict` | 現在の状態と衝突した（HTTP 409） | Sessionなどの状態を読み直し、衝突が解消してから再実行する |
| `network_error` | serverへ接続できない。成否不明として扱わない操作でのHTTP 429もこのcodeになる | 通信を確認し、時間をおいて再実行する |
| `server_error` | serverが5xxを返した | 時間をおいて再実行する。続く場合は報告する |
| `unexpected_response` | 応答が`chat`の想定と合わない、または分類できない失敗 | `chat --version`を記録し、`code`と`message`をsupportへ渡す |
| `output_write_failed` | 結果をstdoutへ書けなかった | 出力先（pipeなど）を確認する |

### 機能ごとのcode

| code | 意味 | 次の操作 |
|---|---|---|
| `ask_wait_timeout` | 指定した待ち時間が過ぎても、Askが開いたままである | `commands`の`chat ask show`で現在の状態を読む |
| `wait_targets_invalid` | 待機の対象（Session・Workflow Run・Ask）が条件に合わない | `commands`の読取りで各IDを確認し、正しい組み合わせを新しいclient nonceで作る（[待機（chat wait）](/ja/docs/cli#待機chat-wait)） |
| `wait_not_found` | 指定した待機が見つからない | 待機ID・元Session・Projectが作成時の受領と一致するか確認する |
| `workflow_not_found` / `workflow_run_not_found` | Workflow、またはそのRunが見つからない | `chat workflow list`や現在のProjectのRun IDで指定し直す（[Workflows](/ja/docs/workflows)） |
| `workflow_bundle_not_ready` | workspaceのmirrorが、Bundleの最新状態を時間内に確認できなかった。何も開始・公開されていない | 編集を加えずに`commands`の同じコマンドを再実行する |
| `draft_version_conflict` | 待つ間にserverのDraftが変わった、または衝突マーカーが残っている。何も送られていない | `data.conflict_files`・`data.changed_files`を読んでマーカーを解消し、同じコマンドを再実行する |
| `workflow_validation_failed` | Workflow Bundleが検証に通らなかった | `data`の検証結果を読んで直す |
| `invalid_workflow_yaml`・`invalid_bundle_path`・`bundle_too_large`・`cyclic_dependency`・`unknown_step_reference`・`invalid_prompt_variable`・`missing_completion_instruction`・`invalid_completion_instruction`・`invalid_input`・`invalid_output`・`rendered_prompt_too_large` | Workflowの定義・入力・出力の検証エラー | `field`・`got`の位置と`message`を読んで直す（[Workflows](/ja/docs/workflows)） |
| `workflow_session_managed` | Workflow Step SessionはWorkflowが終了を管理する | `chat session finish`を再実行しない。このturnを通常どおり終え、Workflowの完了指示に従う |
| `session_pending_follow_ups` | 送信待ちのfollow-upが残っているため、Sessionを終えられない | このturnを終え、次のturnで処理してから`chat session finish`を再実行する |
| `time_trigger_not_found` / `time_trigger_changed` / `time_trigger_conflict` | Triggerが見つからない、読んだ後に変わった、または現在の状態と衝突した | `commands`で最新のTriggerと`state_version`を読み直してから決める（[競合、pause、成否不明から復旧する](/ja/docs/triggers#競合pause成否不明から復旧する)） |
| `time_trigger_request_conflict` / `time_trigger_request_deleted` | 同じ作成要求IDが別内容で使われた、または作成済みのTriggerが削除されている | `message`と`data.mutation_state`を読み、`chat trigger list`で照合する |
| `trigger_target_unavailable` / `trigger_agent_not_found` | Triggerの起動先が使えない、またはagent名に一致するmemberがいない | `commands`の一覧から正確な起動先を選ぶ |
| `webhook_request_required` | Webhook Triggerには時刻のpreviewがない | 認証付きのJSON要求をwebhook URLへ送って確認する（[Triggers](/ja/docs/triggers)） |
| `media_unavailable` | そのMediaはまだreadyでないか、このProjectにない | `commands`の`chat media <project>`に出るまで使えない（[Media](/ja/docs/media)） |
| `media_download_failed` | Mediaの取得に失敗した。ファイルは書かれていない | 一度だけ再実行する。再び失敗したら報告する |
| `media_delete_conflict` | 現在の状態ではMediaを削除できない。Shared DocumentやProject HTMLがまだ参照している場合などに出る | `message`を読み、参照しているファイルから参照を外す。`commands`の`chat media <project>`で読み直し、一覧にある場合だけ削除を再実行する |
| `attachment_upload_failed` | 添付のuploadに失敗した。Sessionへの指示は送られていない | 添付のpathと通信を確認して再実行する |
| `project_lead_not_parent_member` / `ambiguous_project_lead` | 指定したLeadが親Projectのactiveなmemberでない、または複数に一致する | `commands`の`chat project assign`で親Projectへ追加するか、`candidates`から選ぶ |
| `owned_agent_required` | 元Sessionのownerが所有する、削除されていないagentだけを指定できる | 所有するagentを選ぶ。それ以外は権限のある人間の経路で追加する |
| `project_lead_required` | 現在のProject LeadのSessionからだけ実行できる | Project LeadのSessionから再実行する |
| `skill_not_found` / `ambiguous_skill` | feedbackの対象skillがない、または同名が複数ある。feedbackは送られていない | `candidates`から正確な名前を選ぶ。同名なら`--source`を付ける |
| `session_not_active` / `forbidden` | skill feedbackを送れるSessionの状態でない、またはtokenが現在のSessionのものでない | 実行中のSessionから、そのSessionのtokenで送る |
| `message_mutation_failed` | messageを変更できない（存在しない、削除済み、自分のmessageでない、書込み範囲の外など） | `hint`に従い、`chat read <project>`で対象のseqを選び直す |
| `post_type_message_not_found` / `post_type_requires_root_message` / `post_type_message_deleted` / `message_post_type_forbidden` / `invalid_message_post_type` | post typeを変更できないmessageや値を指定した | `chat read <project>`で存在するroot messageを選び、許可された値を指定する |
| `database_sql_execution_failed` / `database_result_too_large` | SQLの実行に失敗した、または結果が大きすぎる | 制約と値を確認してSQLを直す。結果が大きければ列や行を減らす（[Database](/ja/docs/database)） |
| `result_report_incomplete` | 成果の一部が記録されなかった | 示された再送用のpayloadをそのまま再送し、失敗した項目の`message`に従う。元の作業は繰り返さない |
| `result_retry_persistence_failed` | 再送用ファイルの作成または更新に失敗した。送信前後の両方で起こる | `data.mutation_state`・`retry_file_state`・`items`・`retry_payload`を読む。元batchやstaleなfileを再送しない（[成果報告の復旧](/ja/docs/troubleshooting#成果の報告が記録されない)） |
| `inbox_mark_incomplete` | 既読の更新の一部が確認できなかった | `data.unconfirmed`を読み、一覧を読み直す |
| `publication_preparation_failed` | Discover公開の準備に失敗した | `message`の原因を直して再実行する |

## `aachat doctor`の項目とcode

`aachat doctor`の`data.diagnostics.issues[]`（`--view checks`では`checks[]`）の各項目は`id`と`code`を持つ。`code`は既定で`id`と同じで、原因がわかるときだけ別の値になる。状態は`state`（`pass`・`fail`・`unknown`・`skipped`）、重さは`category`（`blocker`・`preservation`・`maintenance`・`information`）で読む。`overall`の読み方は[まず診断する](/ja/docs/troubleshooting#まず診断する)にある。

診断自体が中断した、または子プロセスの回収を確認できなかった場合は`{"ok": false}`・終了コード1になり、`error.code`は`internal_error`、`error.message`は`cancelled`や`probe_cleanup_unverified`である。取得済みの項目は`data`に残る。

### 項目（`id`）

| id | 何を見るか | failやunknownのときの次の操作 |
|---|---|---|
| `platform` | aachatの版とOS | 情報のみ |
| `user_jwt` | 保存されたサインイン情報の期限と形式。`User JWT: expired`は期限切れ | 人間の承認を得て`aachat auth login`を実行する（[認証で失敗する](/ja/docs/troubleshooting#認証で失敗する)） |
| `github_cli` | `gh`があるか | `gh`を入れる |
| `github_auth` | `gh auth status`を確認できたか。unknownは未認証の証拠ではない | `gh auth status`を読む |
| `github_scopes` | GitHub tokenに`repo`・`read:user`のscopeがあるか | failなら人間に`gh auth refresh -s repo,read:user`を依頼する |
| `node` | Node.jsがruntime adapterの最低版を満たすか | 対応版のNode.jsを入れる |
| `chat_companion` | 同梱の`chat`があり、CLIと同じ版か | CLIの導入を確認し、`aachat doctor`を再実行する |
| `runtime_path` / `login_shell_path` | runtimeのPATHを組み立てられるか、login shellのPATHを取得できたか | PATHの設定を確認する。値は共有しない |
| `provider_readiness` | 常に未検査（`not_applicable`）。providerのログインやモデル呼出は行わない | 情報のみ |
| `wsl2_systemd` / `loginctl_linger` | Linux・WSL2のuser service設定。他のOSでは`not_applicable` | `message`の手順で確認する。設定変更は人間の承認を得る |
| `api_health` / `api_workspace_handshake` | APIへ届くか、保存済みサインイン情報でworkspace APIを呼べるか。失敗時の`code`は`network_error`・`auth_required`・`server_error`など`aachat` CLIのcodeになる | `aachat status`で接続と認証を確認する |
| `daemon` | `aachat up`のprocessが動いているか | 停止中なら人間に`aachat up`を依頼する |
| `project_workspace_host` / `project_workspace_repo` | 投影（Project文書などを手元に写す仕組み）の配置に障害がないか。`code`は下の投影の配置codeになる | 下の表を読む |
| `projection` / `projection_observation` / `projection_write` / `projection_project` / `projection_team` / `projection_sync_time` | 同期の状態。`code`は下の同期codeになる | 下の表を読む |
| `session_workspace_capacity` | Session workspaceの置き場所に20 GiBの空きがあるか | [空き容量不足でSessionが始まらない](/ja/docs/troubleshooting#空き容量不足でsessionが始まらない)を読む |
| `session_workspace_maintenance` / `session_workspace_retained` / `session_workspace_artifact` | 保持されたSession workspaceの検査結果。`code`は下のworkspace保守codeになる | 作業を保全してから、各項目の`next_actions`に従う |

### 検査が終わらなかったときのcode

| code | 意味 | 次の操作 |
|---|---|---|
| `probe_timeout` | 検査が時間内に終わらなかった。その項目は未確認である | 他の項目は有効である。対象を絞って確認する |
| `probe_output_limit` | 検査の出力が上限を超えた | 同上 |
| `probe_failed` | 検査を完了できなかった。必要な実行ファイルがない場合も出る | `reason`を読み、該当する依存を確認する |
| `cancelled` | 中断された。後の検査は`skipped`になる | もう一度実行する |
| `probe_cleanup_unverified` | 検査の子プロセスの回収を確認できなかった。後の検査は`skipped`になる | もう一度実行する。続く場合はsupportへ渡す |
| `not_applicable` | この環境では対象外（他のOS、`aachat up`停止中の同期項目など）。未完了扱いにはならない | 不要 |
| `workspace_inspection_complete` / `workspace_inspection_incomplete` | workspace検査の要約。completeは観測範囲の分類と計測が終わったという意味で、問題なしではない | incompleteなら`coverage`を読み、未確認の範囲を絞って調べる |

### 同期のcode

| code | 意味 | 次の操作 |
|---|---|---|
| `sync_protocol_version_mismatch` | CLIの同期protocolがserverと合わず、同期が止まった。最後に同期したファイルは残るが最新ではない | 自動更新の途中かを確認し、`aachat update`の後に人間に`aachat up`の再起動を依頼する（[`aachat up`が起動失敗する・途中で止まる](/ja/docs/troubleshooting#aachat-up-が起動失敗する途中で止まる)） |
| `workspace_mirror_error` | 最後に観測したrepo側のmirrorがerrorだった。今の同期は未確認である | `aachat status`で現在の状態を読む |
| `projection_write_blocked` | 手元の書込み、または診断ファイル（`_errors.md`）で同期が止まっている | 診断の原因を直す。生成された`_errors.md`は編集しない（[Shared Documentsが同期されない](/ja/docs/troubleshooting#shared-documentsが同期されない)） |
| `projection_pending` | 手元の書込みが未送信である | 送信の完了を待ち、`aachat status`で確認する |
| `projection_observation_failed` | このpathの観測に失敗した。件数は一部だけである | pathの権限とfilesystemを確認する |
| `project_sync_failed` / `sync_list_unstable` / `invalid_sync_list` | Projectの同期に失敗した。後の二つはserverから受け取った一覧が安定しない・不正な場合である | `aachat status`で対象Projectの状態を読み、時間をおいて確認する |
| `project_sync` / `projection` / `team_projection` | 該当する問題のcodeがない同期項目の既定値 | `state`と`reason`を読む |
| `team_projection_revoked` | Teamへのアクセスが取り消され、Teamの投影が止まった | 人間にTeamへのアクセス回復を依頼する |
| `projection_sync_time` | 同期の成功時刻がない・不正・未来である | `aachat status`で確認する |

### 投影の配置のcode

`project_workspace_host`・`project_workspace_repo`の`code`、および`aachat status`の`projection.reason`の先頭に出る。

| code | 意味 | 次の操作 |
|---|---|---|
| `projection_namespace_migration_required` | 旧形式の投影の状態が残っている。通常の起動では移行しない | [layout移行が必要と言われる](/ja/docs/troubleshooting#layout移行が必要と言われる)を読み、`aachat support`を起動する |
| `projection_namespace_migration_pending` | 旧形式からの移行が途中で止まっている | rootを保全し、`aachat support`で復旧する |
| `projection_namespace_split_brain` | 旧形式の状態と新形式の状態が同時にある | workspaceを保全し、`aachat up`を再起動する前に復旧する |
| `projection_unknown_top_level_entry` | 投影の管理領域に未知のファイルがある | そのファイルを管理領域の外へ移し、`aachat up`を再起動する |
| `projection_root_invalid` / `projection_owner_root_invalid` | 投影の管理領域がlocal directoryでない（symlinkなど） | local directoryに置き換え、`aachat doctor`を再実行する |
| `projection_root_unreadable` / `projection_owner_root_unreadable` / `projection_entry_unreadable` | 投影の管理領域を読めない | 読取り権限を戻し、`aachat doctor`を再実行する |
| `project_workspace_projection_invalid` | Project workspaceの投影の状態が不正である | `aachat support`を起動する。生成されたbaselineや診断を直接編集しない |
| `project_workspace_layout_upgrade_available` | layout 7をlayout 8へ上げられる（通知のみ） | 不要。次のSession起動で記録だけが更新される |

### workspace保守のcode

`session_workspace_maintenance`・`session_workspace_retained`の`code`に出る。どれも削除の許可ではない。手元の作業を保全してから対応する。

| code | 意味 |
|---|---|
| `uncommitted_workspace_changes` / `uncommitted_agent_changes` | 未commitの変更がある |
| `local_workspace_commits` / `local_agent_commits` | pushが確認できないcommitがある（手元のremote-tracking refだけで判定） |
| `non_git_workspace_files` | Git管理でないworkspaceにファイルがある |
| `wiki_local_work` | 未保存のWiki下書きがある |
| `builtin_agent_local_work` | 組み込みAgentのsnapshotに編集がある |
| `agent_owned_workspace_head` | HEADがaachat管理のbranchでないため、agentのGit状態として保持した（`session_workspace_retained`、情報のみ） |
| `agent_cleanup_metadata_missing` | 片付けに必要な記録がない |
| `git_inspection_failed` / `cache_lock_failed` / `common_git_dir_missing` | Gitの状態を確認できなかった |
| `worktree_remove_failed` / `branch_remove_failed` / `scratch_workspace_remove_failed` / `builtin_agent_remove_failed` / `workspace_identity_remove_failed` | 削除に失敗した |
| `workspace_repository_mismatch` / `workspace_repository_unknown` | workspaceのrepositoryが記録と違う、または確認できない |
| `workspace_identity_missing` / `workspace_identity_invalid` / `workspace_identity_mismatch` / `orphan_workspace_identity` | workspaceの所有Sessionの記録がない・不正・食い違う、または対応するworkspaceがない |
| `workspaces_dir_unreadable` / `workspace_entry_unreadable` / `workspace_identities_dir_unreadable` / `workspace_identity_entry_unreadable` / `workspace_identity_target_unreadable` / `workspace_identity_unreadable` / `scratch_workspace_unreadable` / `scratch_workspace_entry_unreadable` | 読取り権限などで読めない |
| `workspace_inventory_boundary_unknown` / `scratch_workspace_boundary_unknown` | filesystemの境界を確認できない |
| `wiki_inspection_failed` | Wiki下書きの確認に失敗した |

次の操作は各項目の`next_actions`に出る。未commit・未pushの作業は、commit・pushするか別の場所へ保存する。「読めない」「確認できない」系は権限とpathを確認し、`aachat doctor`を再実行する。

## `aachat status`の`warnings[]`と状態の値

`aachat status`は成功しても`warnings[]`と`next_actions`を返すことがある。次に行う操作は`next_actions`に出る。

| `warnings[].code` | 意味 | 次の操作 |
|---|---|---|
| `project_sync_unavailable` | 一部のProjectの同期が使えない。最後に同期したファイルは残り、そのProjectへの書込みは止まる | `aachat doctor`の`projection_project`で対象と原因を読む |
| `session_workspace_capacity` | Session workspaceの空きが20 GiBを下回る、または測れない | `message`の指示に従う（[空き容量不足でSessionが始まらない](/ja/docs/troubleshooting#空き容量不足でsessionが始まらない)） |
| `session_workspace_capacity_incomplete` / `session_workspace_capacity_unavailable` | 容量の検査が時間内に終わらなかった、または実行できなかった | `aachat doctor`で容量を確認する |
| `session_workspace_maintenance` | 過去のworkspaceに手元の作業や要確認のものがあり、保存された。runtimeの起動は妨げない | `aachat doctor`でpathと手順を読む |

| field | 値 | 意味 |
|---|---|---|
| `connection.state` | `ready` / `connected` / `missing` / `invalid` / `unavailable` | 接続とTeamアクセスを確認済み / 手元の接続だけ確認 / repo外か接続なし / 接続情報が不正 / 未登録・Teamが見えない・確認できない |
| `auth.state` | `valid` / `expired` / `missing` / `invalid` / `unavailable` | 保存されたサインイン情報の状態。`unavailable`は読めなかった |
| `daemon.state` | `running` / `stopped` / `unknown` | `aachat up`の稼働状態 |
| `projection.state` | `running` / `stopped` / `error` / `blocked` / `missing` / `unknown` | 同期中 / 停止中 / 同期に障害がある（protocol不一致を含む） / 投影の配置に障害がある / 投影先が未作成 / 確認できない |
| `gaps[].code` | `unavailable` | その`field`を観測できなかった。問題がないという意味ではない |

`projection.state`が`blocked`のとき、`projection.reason`は`<code> at <path>: <説明> Next: <次の操作>`の形で、`<code>`は[投影の配置のcode](#投影の配置のcode)である。`error`のときの読み方は[`aachat up`が起動失敗する・途中で止まる](/ja/docs/troubleshooting#aachat-up-が起動失敗する途中で止まる)にある。

## Launch Reportのカテゴリ

`aachat up`は、agentごとの起動結果をLaunch Reportとして`up.log`に書く。失敗したagentは`[failed] <agent>`の下に`Error [<カテゴリ>]: ...`と`action:`が並ぶ。agentの`[failed]`があっても`aachat up`自体は動き続ける。

`aachat up`自体が失敗して終了したときは、同じカテゴリが`up.log`に出て、終了コードはカテゴリで決まる。

| カテゴリ | `aachat up`自体が終了したときの終了コード | 見る場所 |
|---|---|---|
| `PREREQ` | 2 | `aachat doctor`の指示。不足しているtool |
| `CONFIG` | 2 | 表示されたagent repoのファイルや設定 |
| `AUTH` | 3 | `gh auth status`。必要なら人間が`gh auth login`を実行する |
| `NETWORK` | 4 | 通信とserverの状態 |
| `API` | 1 | serverの状態と`message` |
| `PERMISSION_DENIED` | 1 | Team・Projectのアクセス権 |
| `GIT` | 1 | GitHubへの接続・認証・branch設定と、agent repoの状態 |
| `CAPACITY` | 1 | `aachat doctor`の保持workspaceと空き容量（20 GiB） |
| `IO` | 1 | 表示されたpathのファイル |

カテゴリごとの対処と`Runtime Health`の読み方は[`aachat up`が起動失敗する・途中で止まる](/ja/docs/troubleshooting#aachat-up-が起動失敗する途中で止まる)を読む。

## Sessionの失敗と起動時のcode

Sessionが起動の準備中に失敗すると、Sessionの`runtime_facts.bootstrap.failure`に`step`（失敗した準備の段階）・`message`・`code`・`subject`が残る。WebUIは`message`と`Initialization step: <step>`を表示する。`code`は次の4つで、ほかの失敗では付かない。どれもpromptを送る前の失敗である。Workflow Stepでは、同じcodeがAttemptの失敗として出る。Step SessionがこれらのcodeなしでSession失敗したときは、Attemptの失敗codeは`session_failed`になる。

| code | 意味 | 次の操作 |
|---|---|---|
| `workspace_capacity_insufficient` | Session workspaceの空きが20 GiBに足りない。toolの実行やworkspaceの作成は始まっていない | [空き容量不足でSessionが始まらない](/ja/docs/troubleshooting#空き容量不足でsessionが始まらない)を読む |
| `config_not_offered` | 指定したRuntime設定（`subject`のoption）をruntimeが提供していない | 設定を外すか、別のRuntimeを選ぶ。Workflowなら`chat project members <project> --runtime-profiles`で確認して`workflow.yaml`を直す（[Runtimeとモデルの既定値](/ja/docs/agents#runtimeとモデルの既定値)） |
| `config_value_not_accepted` | 指定した値をruntimeが受け付けない | 提供されている値を選ぶ |
| `config_not_proven` | 設定が適用されたことを確認できなかった（拒否・timeout・読めない応答を含む） | runtimeとadapterを確認する。Workflowで同じ設定のままでよければ、retryできるStepだけをretryする |

`aachat session list`・`session read`の結果では、失敗したSessionの`error`が`{"code": "session_failed", "message": ...}`となる。一覧の`attention.items[].code`は`permission_pending`（許可の回答待ち）・`submission_pending`（未処理の依頼がある）・`failure`（失敗した）である。失敗したSessionの続け方は[Sessionが失敗した・途中で止まった](/ja/docs/troubleshooting#sessionが失敗した途中で止まった)を読む。