---
id: troubleshooting
title: 困ったときは
category: basic
order: 80
keywords: [トラブル, エラー, 失敗, waiting, スタック, 再試行]
---

# 困ったときは

よくある状況とその対処をまとめます。解決しない場合は、ヘルプ画面の **「AI に聞く」** から help アシスタントに症状を伝えるか、管理者に問い合わせてください。

## タスクが「回答待ち（waiting_human）」で止まっている

エージェントが依頼の曖昧な点を確認したい、または作業を進めるために情報が必要なときに、この状態になります。

**対処**: タスク詳細のチャットパネルに「エージェントからの確認」が表示されているので、**質問に回答を送る** とタスクが再開します。回答すべき内容が分からない場合は、不足している情報（対象ファイル・期待する出力形式など）を補足してください。

なお、確認の回数には上限があり、上限に達すると回答待ちのままにはならず終了することがあります。その場合は、依頼文を具体化して新しいタスクを作り直すのが確実です。

## タスクが「サブタスク待ち（waiting_subtasks）」で止まっている

そのタスクが生成した子タスク（サブタスク）の完了を待っている状態です。

**対処**: タスク詳細の **サブタスク タブ** で子タスクの一覧と状態を確認します。子タスクが失敗していれば、その失敗理由を確認して解消します。子タスクが進行中なら、完了すれば親タスクは自動で再開します。サブタスクの仕組みは [サブタスク](10-subtasks.md) を参照。

## タスクが失敗した（failed）/ 再試行について

タスクは失敗しても、設定された最大試行回数まで自動で再キューされて再実行されます。再実行時には前回の失敗内容が引き継ぎコンテキストとして渡され、同じ作業の重複を避けようとします。再試行中はチャットのヘッダーに **試行 2/3** のバッジが表示され、ホバーすると前回の中断理由が確認できます。

**対処**:

- タスク詳細の概要・タイムラインでエラー内容を確認する
- 入力ファイルや依頼文に問題があれば修正して新しいタスクを作る
- 最大試行回数を使い切っても失敗し続ける場合は、依頼を分割するか、より能力の高いモデルでの実行を管理者に相談する

## 「⚠️ 中断」メッセージの読み方

LLM 起因で中断したタスクの中断メッセージには、1 行目に失敗の分類が入ります。

- **分類: context_overflow** — 会話がモデルのコンテキスト上限を超えた。依頼を分割するか、大きなファイルの全文読み込みを避ける指示を足す
- **分類: idle_timeout / hard_cap** — LLM バックエンドが規定時間内に応答を返さなかった（idle_timeout）か、1 回の応答が長すぎて上限で打ち切られた（hard_cap）。バックエンドの負荷や暴走生成のサイン
- **分類: gateway_timeout / gateway_shutdown** — LLM ゲートウェイ（配車側）がバックエンドとの通信を打ち切った。特定バックエンドの不調が疑われる
- **分類: http (HTTP 5xx) / connection** — バックエンドがエラーを返した、または接続できなかった

どの LLM 呼び出しで何が起きたかの詳細は、詳細パネルの **トレース** タブで確認できます。各呼び出しの所要時間・トークン数・リトライ回数・担当バックエンド・エラー分類が 1 行ずつ記録されています。

## エージェントが「ログインを要求された」と返す

タスク中のブラウザ操作（BrowseWeb）で、保存済みのログイン情報が期限切れになっているとこのメッセージが返ります。

**対処**: ワークスペース → 設定 → ブラウザ で対象セッションを開き、「再ログイン」して保存し直します。詳しくは [個人の資産（ワークスペース設定）](09-userfolder.md) を参照。ログイン情報（cookie）は時間が経つと失効するため、定期的なメンテナンスが必要です。

## 成果物が output/ にあるはずなのに見えない

**対処**:

- タスク詳細の **Files タブ** で「output」セクションを選んでいるか確認し、リフレッシュでファイルツリーを再取得する
- 大きすぎるテキストはプレビューが切り詰められることがあります。元ファイルはダウンロードして確認してください

成果物の見方は [成果物を見る](04-results.md) を参照。

## PowerPoint プレビューが「変換エンジン未導入」と出る

`.pptx` / `.ppt` のプレビューは、サーバー側で LibreOffice を使ってスライドを画像化します。これが未導入のサーバーでは、プレビューの代わりにダウンロード案内が表示されます。

**対処**:

- Docker で動かしている場合は最新イメージで再ビルドしてください（イメージに LibreOffice を同梱済み）
- 直接（非 Docker）で動かしている場合は、サーバーに LibreOffice を入れます: `sudo apt install --no-install-recommends libreoffice-impress`。起動時の依存チェック（`scripts/prepare.sh`）でも未導入なら警告が出ます
- Excel（`.xlsx` / `.xlsm`）のプレビューは LibreOffice 不要です（未導入でも表示できます）

## ログの場所

調査の手がかりはログにあります。

- タスクごとのアクティビティ・ダウンロード履歴などは、タスク詳細の **Files タブ → logs/** にあります（[成果物を見る](04-results.md) 参照）
- サーバー全体のログは管理者が `scripts/server.sh logs` で確認できます。詳しく見たいときは `LOG_LEVEL=debug` で再起動します

## 「AI に聞く」を使う

ヘルプ画面の「AI に聞く」ボタンを押すと、help アシスタント（help piece）への質問タスクが作られます。MAESTRO の使い方・設定・エラーの意味など、画面の操作で迷ったときや原因の当たりを付けたいときに使ってください。

具体的な操作手順の確認には [タスクを実行する](03-running.md) も合わせて参照してください。それでも解決しない場合は管理者に問い合わせてください。
