トラブルシューティング
サーバーが起動しない
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 を返します。