メインコンテンツまでスキップ

トラブルシューティング

サーバーが起動しない​

  • OBSIDIAN_AI_HUB_API_TOKEN が空 — 空だとサーバーは起動に失敗します。.env に設定してください。
  • Vault 設定が不正 — config/config.yml の vaults(main 必須・唯一の role: primary、存在する重複なし・入れ子なしのディレクトリ、 ai_access は none / read / write のいずれか)が不正だと Web は起動しません。 make status-web に starting / ready / failed と最後のエラー理由が表示されるので、まずここを確認します。
  • ポートが使用中 — --serve-port で別ポートにするか、lsof -ti :8765 | xargs kill で解放します(LaunchAgent 登録後は make restart-web が行います)。
  • フロントエンドが未ビルド(503) — make build-web を実行して frontend/dist を生成します。

Vault 検索が使えない​

  • 索引が古い / 無効 — Vault ID の path を変更した後は、その ID の既存索引は使われません。 uv run -m obsidian_ai_hub --rebuild-vault --vault <id> が成功するまで検索対象に戻りません。
  • AI からの検索に出ない — ai_access: none の Vault は AI の検索・読取り対象外です(人間の Web UI / CLI からは操作できます)。 AI の書込みが拒否される場合は ai_access が write か、main への汎用書込みでないかを確認します (main への汎用 AI 書込みは常に拒否されます)。

ブラウザで「接続エラー」になる​

ヘルスチェック GET /health に到達できていません。 サーバーが起動しているか、ホスト / ポートが一致しているかを確認し、再読み込み します。

トークン関連​

  • 入力しても弾かれる — .env の OBSIDIAN_AI_HUB_API_TOKEN と完全に一致しているか確認します(大文字小文字・空白)。
  • 401 が返る — トークンが失効・変更されています。設定 画面で再入力してください。
  • ジョブ管理で 403 — アクセス制限画面が表示された場合、トークン認証とネットワーク(localhost または tailnet)を確認します。
  • 設定の保存に失敗 — トークンが無効です。設定 画面の入力を確認してください。

ジョブが実行されない​

  • tasks/ が残っている — runner は起動を拒否します。uv run -m obsidian_ai_hub.job_runner --migrate-tasks-to-jobs で移行してください。
  • 設定 YAML が壊れている — 破損した jobs.local.yml は空として扱われず、明示的にエラーになります。内容を修正してください。
  • arming のため遡って実行されない — 追加・再有効化・コマンド/スケジュール変更時は保存時刻で arming されます。次の該当枠を待つか、last_run を確認してください。
  • 失敗が繰り返される — 失敗時は last_run が更新されず、後続サイクルで再試行されます。コマンドとログを確認します。
  • 常駐 HITL ワーカーと二重 — 常駐ワーカー稼働中は hitl_dispatch を定期ジョブにしないでください。

LLM API の一時的な失敗(5xx / 429 / タイムアウト)​

  • プロバイダ側の 5xx(例: InternalServerError)、429(レート制限)、接続タイムアウトは自動で再試行されます(上限 4 回、指数バックオフ+ジッター、待機は最大 30 秒)。
  • 上限まで失敗した場合はコマンド自体が失敗として記録されます。日次要約などは「対象日・処理段階」を含むエラーになり、同日の既存サマリーは上書きされません。
  • 失敗した LLM コールの詳細には、プロバイダへ問い合わせるための情報(HTTP ステータス、リクエスト ID、試行回数、応答本文の要約)が [llm-diagnostics] として保存されます(API キー等の機密情報は伏せ字)。実行ログ → ログ の LLM 詳細で確認できます。
  • 同じ失敗が繰り返される場合は、プロバイダの障害情報・モデル提供状況・認証情報の設定を確認してください。

Task / ワークフローが進まない​

  • Web サーバーが停止していると進みません。 Task はキューに残り、Run も実行されません。
  • interrupted の Task は 再計画、interrupted の Run は 再開 で戻します。
  • ワークフローの承認待ち・HITL 待ち・attention 待ちは、それぞれの画面で処理します(Run・承認・復旧)。

ワークフローの検証・実行エラー​

制約とトラブルシューティング を参照してください。 とくに「実行には公開が必要」「公開済み Revision は編集不可」はよくあるつまずきです。

リサーチのコードベース調査が使えない​

project モードは有効な Git リポジトリのプロジェクトのみ選べます。 プロジェクト管理 でプロジェクトを登録・確認してください。

ENV=test で外部サービスにつながらない​

テストモードでは LLM・LINE・カレンダー・Web 検索などが既定でブロックされます。 必要な場合のみ .env.test に ALLOW_EXTERNAL_IN_TEST=1 を設定してください。

Apple 連携のエラー​

プランナー画面に「Apple連携でエラーが発生しました」と表示される場合、 APPLE_CALENDAR_NAME の設定、カレンダー / リマインダーへのアクセス権限を確認してください。

旧 URL が 404 になる​

  • Web UI: /tasks → /jobs へ移動しました。
  • API: /api/v1/task-config → /api/v1/scheduler-jobs(recurring: recurring-jobs、one-shot: one-shot-jobs)へ移動しました。旧 URL は 404 を返します。

参考​