未翻訳のページは英語で開き、英語と表示されます。
このページは英語の原文の機械翻訳です。内容は英語の原文が優先されます。 Machine-translated from the English page, which is authoritative.
トラブルシューティング
各項目では、症状、原因を確認するためのチェック、そして対処方法を示します。1 件のリクエストを台帳、クエリログ、トレースにわたって追跡するには、リクエストのデバッグを参照してください。
はじめに
ログを読む前に、次の 3 つのコマンドでほとんどの疑問に答えが出ます。
curl -s http://localhost:7777/v1/health | jq '{status, ch_ok, ch_error, schema, problems}'
docker exec loom-server loom doctor # the same problems, plus pre-boot checks
curl -s -XPOST http://localhost:7777/v1/ops.health -H "Authorization: Bearer $ADMIN_TOKEN" \
-H 'Content-Type: application/json' -d '{"org":"<org>"}' | jq # ClickHouse parts, workers, stubs (ORG_ADMIN)
problems の各エントリには fix が含まれています。まずそれを読んでください。クライアントマシンでは、loom doctor --client が、SDK とフックが解決するサーバー URL とトークンを確認します。各フィールドの意味については、モニタリングを参照してください。
サーバーと ClickHouse
すべての操作が失敗し、/v1/health が 503 を返す
- 原因: サーバーから ClickHouse に到達できません。起動も最初のマイグレーションで停止します。
- 確認:
curl -s localhost:7777/v1/health | jq .ch_errorを実行し、続けてdocker exec loom-server loom doctor(clickhouse_reachableの行)を実行します。 - 対処:
LOOM_CH_HOST/LOOM_CH_PORT/LOOM_CH_USER/LOOM_CH_PASSWORDを修正します。ポート 8443 は TLS を前提とします。それ以外のポートで TLS を使う場合はLOOM_CH_SECURE=trueを設定します。ClickHouse Cloud では、サービスが稼働していること(アイドル状態のサービスは一時停止します)と、IP 許可リストに Loom のホストが含まれていることを確認します。
loom up がタイムアウトする、またはコンテナーが起動時に終了する
- 原因: 多くの場合、マイグレーションまたは ClickHouse のエラー、
.envの値の不正、あるいは compose ファイル外のプロセスでLOOM_INSTANCE_LABELが未設定であることが原因です。 - 確認:
docker logs loom-serverを実行します。失敗したマイグレーションファイルや設定名がログに記載されています。env ファイルはdocker compose --env-file .env -f dev/docker-compose.cloud.yml config >/dev/nullで検証します(起動に使う compose ファイルを指定してください)。 - 対処: ログに出ているエラーに対処します。認証が有効で、リポジトリに含まれる開発用の
LOOM_JWT_SECRETを使った状態のデプロイ(LOOM_DEPLOYMENT=1)は、仕様として起動を拒否します。実際のシークレットを設定してください(デプロイ)。
書き込みが TOO_MANY_PARTS で失敗する、またはマージが失敗している
- 症状: 書き込みが ClickHouse エラー 252
TOO_MANY_PARTSで失敗する、またはops.healthがclickhouse_parts: failを報告します。 -
確認: マージが失敗していないかを確認します。原因は書き込み頻度ではなく、ほとんどの場合マージの失敗です。まず
system.part_logのマージエラーを読みます。SELECT table, error, count() AS failures, any(exception) FROM system.part_log WHERE database = 'loom' AND event_type = 'MergeParts' AND error != 0 AND event_time > now() - INTERVAL 1 HOUR GROUP BY table, error;
-
対処: 例外メッセージでサーバーがマージできないスキップインデックスが示されている場合は、そのインデックスをマージ時のマテリアライズから除外します。この設定はメタデータのみの変更で、元に戻せます。挿入されたパートでは引き続きインデックスが構築されます。
ALTER TABLE loom.<table> MODIFY SETTING exclude_materialize_skip_indexes_on_merge = '<existing list>,<index name>';マージが成功するようになれば、パート数は数分で減少します。先にインデックスを削除しないでください(後で再構築するとテーブルが書き換えられます)。また、
parts_to_throw_insertを引き上げるだけにしないでください。マージが止まっている間はパート数が増え続けます。マージが失敗していない場合は、1 ステートメントにつき 1 行ずつ挿入しているライターを探します(system.query_logをlog_commentで集計します。クエリの帰属を参照)。
ClickHouse Cloud のレプリカ再起動後に書き込みに数秒かかる
- 症状: 読み取りは高速なまま、書き込みの多い操作(
memory.set、run.*、conversation.append)に数秒かかります。エラーは出ません。デプロイ直後に起きることが多いものの、デプロイは原因ではありません。 -
確認: レプリカの稼働時間と、システムログの再アタッチが進行中かどうかを確認します。
SELECT hostName(), uptime() FROM clusterAllReplicas(default, system.one); SELECT count() FROM system.query_log WHERE event_time > now() - INTERVAL 15 MINUTE AND query ILIKE 'ATTACH TABLE system.%';
- 対処: Loom 側で行うことはありません。再起動後しばらくの間、サービスはシステムテーブルを再アタッチしており、それが完了すると挿入は回復します(通常は 1 時間以内)。この件を理由にデプロイをロールバックしないでください。解消しない場合は ClickHouse Cloud のサポートに問い合わせてください。
リクエストが BACKEND_TIMEOUT または OVERLOADED で失敗する
- 原因: ClickHouse のステートメントがクラスごとのデッドラインを超えた(504
BACKEND_TIMEOUT)か、プロセスのプール済み ClickHouse 接続がすべて使用中のままだった(503OVERLOADED)場合です。書き込みが持続的に多いと、バッチ挿入(監査行、トランスクリプトのターン、agent_events のフラッシュ)は最大LOOM_CH_BATCHED_INSERT_WAIT_MAX_MSの間、さらにフラッシュの間も接続を保持します。バックグラウンドのバッチ挿入(usage-event と write-mark のフラッシュ)は最大LOOM_CH_BATCHED_INSERT_BACKGROUND_WAIT_MAX_MSの間、さらにフラッシュの間も接続を保持します(バッチ挿入)。OVERLOADEDは、ステートメントが、サーバーまたは ClickHouse ユーザーのメモリ不足に遭遇した場合にも発生します(コード 241。すべてのクエリで共通です。サーバーログに ClickHouse の行を伴うClickHouse is short of memoryが 5 秒に 1 回出力されます)。conversation.deleteまたはconversation.compactでは、OVERLOADEDは、スレッドの埋め込みへの書き込みが 8 回のリコンサイルラウンドにわたって続いたことも意味します。スレッドの書き込みが落ち着いてから再送してください。 - 確認:
system.query_logでlog_commentごとに最も遅い発行元を確認します(モニタリング)。パートの圧迫はops.healthで確認します。メモリについては、system.query_logのexception_code = 241のステートメントと、その近くにある最大のmemory_usageを、サーバーのmax_server_memory_usageおよびユーザーのmax_memory_usage_for_userと照らし合わせます。 - 対処: 支配的になっているクエリまたはワーカーに対処します。メモリの場合は、そのステートメントに対処するか、ClickHouse サービスのメモリを増やします。ClickHouse から遠い Loom(WAN 越し)では、レイテンシ予算が呼び出しのたびに発動しないよう、
LOOM_LATENCY_BUDGET_MULTIPLIERを 20 前後にする必要があります。書き込みが持続的に多い状況でのOVERLOADEDでは、バッチ挿入が保持する接続数に合わせてプールのサイズを決めます(バッチ挿入)。次のいずれかを行います。LOOM_CH_POOL_MAXSIZEを引き上げる(再起動が必要です)。切り替え対象のグループでloom settings set ch_batched_inserts falseを使ってバッチ処理を無効にする(起動時はLOOM_CH_BATCHED_INSERTS=false。待機する非同期挿入は引き続き待機します)。loom settings set ch_batched_insert_wait_max_ms <ms>(およびch_batched_insert_background_wait_max_ms)で挿入の待機時間を実行中に短くする。 ライブでの上書きについてはランタイム設定を参照してください。すべてのコードはエラーリファレンスに一覧があります。
プロバイダーと検索品質
検索が 503 EMBED_TIMEOUT で失敗する
- 原因: 埋め込みプロバイダーが、デフォルトでは 2 回の試行(再試行は 1 回、
LOOM_MEMORY_SEARCH_EMBED_BOUND_RETRIES)のどちらでも、LOOM_MEMORY_SEARCH_EMBED_BOUND_S(2.5 s)以内にクエリの埋め込みを返しませんでした。ベクトルが埋め込みキャッシュにあるクエリは、引き続き応答します。 - 確認: サーバーログの
query embed exceeded …s (attempt n/m)という警告と、error_code = 'EMBED_TIMEOUT'のloom.agent_eventsの行を確認します。応答しないプロバイダーはヘルスフラグを立てません。/v1/healthにprovider_failing:<name>が表示されるのは、プロバイダーがエラーも返している場合だけです。プロバイダーのステータスページも確認してください。 - 対処: 生の HTTP や MCP の呼び出し元は 1 回再試行します。SDK の呼び出し元はすでに再試行済みなので、バックオフします。繰り返し発生する場合は、プロバイダーが遅いか停止しています。復旧を待つか、遅いながらも応答しているプロバイダーに対しては上限値を引き上げてください。失敗した検索は、1 回の試行につき最大で上限値の時間、サーバーを占有します。
検索が無関係な結果を返す、または抽出が何も書き込まない
- 症状:
set_from_messagesがファクトを書き込まない、memory.askが空の回答を返す、または検索が文字の重なりで順位付けされる。 - 原因: プロセスが fake プロバイダーで動作しています。fake に設定されている場合(
LOOM_LLM_PROVIDER=fake。標準の.envはすべてこの設定です。あるいはチェックアウトした.envやアップグレードしたインストールのfake-ngram-*埋め込み)、または実プロバイダーに設定されているのにキーがない場合です。 - 確認:
curl -s localhost:7777/v1/health | jq '.problems[].code'がllm_key_missing、embedder_key_missing、fake_llm、fake_embedderのいずれかを示します(本文ではfake_llm: true、fake_embedding: true)。 - 対処: problem の
fixに示されたキー(OPENAI_API_KEY、ANTHROPIC_API_KEY、GEMINI_API_KEY)と、.envのプロバイダーブロックを設定し、コンテナーを再作成します(docker compose … up -d --force-recreate)。キーを設定するだけでは、.envでfakeに固定されたプロバイダーは変わりません。ローカルスタックではベクトルの幅がテーブル作成時に固定されるため、fake の埋め込みから切り替えるにはmake down-all && make devが必要です。fake の埋め込みで埋め込まれた行にはloom reembedが必要です。次回からこれがstatus: degradedと表示されるように、LOOM_REQUIRE_REAL_PROVIDERS=trueを設定してください。
埋め込みモデルの変更後に検索品質が低下した
- 原因: 新しい埋め込みモデルにより、すべての類似度スコアが変化します。古いモデルで埋め込まれたままの行は、別のベクトル空間にあります。
- 確認:
loom reembed --dry-runが、モデルが異なる行を数えます。loom.search.top_similarityで変化を確認できます。 - 対処:
loom reembedを実行し(メンテナンス)、loom.search.top_similarityに対するアラートのベースラインを取り直します。LOOM_ADAPTIVE_THRESHOLDSが有効(デフォルト)の場合、起動時のプローブの後、類似度のゲートは新しい埋め込みモデルに追従します。loom recalibrateを実行すると、すぐに再実行されます。
書き込みが検索に出てこない、または保存されなかった
- 確認: インジェストパイプラインが破棄または切り詰めた内容は
loom drops --namespace NSで確認し、その書き込み自体のレスポンス(status、競合の判定、pipeline_errors)も確認します。loom.embed.pendingは、ベクトル待ちの行を数えます。 - 対処: ドロップの理由に従ってください(メンテナンス)。競合した書き込みは、ダッシュボードの Review キューで解決します(競合と拒否)。
認証とトークン
リクエストが 401 AUTH_INVALID または 503 AUTH_UNAVAILABLE で失敗する
- 症状: 401
AUTH_INVALID、またはRetry-After: 5を伴う 503AUTH_UNAVAILABLE。 - 確認: エラー詳細の
message(期限切れ、署名不正、失効済み、bearer の欠落)を確認します。クライアントマシンでは、loom doctor --clientが、フックと SDK が送信するトークンを検査します。 - 対処:
- 署名不正は、トークンが別の
LOOM_JWT_SECRETで発行されたことを意味します(シークレットをローテーションした、または別のデプロイ向けに発行した場合)。docker exec loom-server loom mint-token …で再発行してください。 - 期限切れまたは失効済みのトークンは、新しいトークンが必要です。
loom revoke-token --listで失効の一覧を確認できます。 - 起動直後の
AUTH_UNAVAILABLEは、失効リストがまだ読み込まれていないこと(revocation_not_loaded)を意味します。読み込みが完了するまでサーバーはトークンを拒否するため、数秒後に再試行し、続く場合は ClickHouse を確認してください。 - 環境内に古い
LOOM_API_KEYが残っていると、SDK とプラグインでは~/.loom/tokenよりそちらが優先されます。 - 認証を初めて有効にした後は、すべての呼び出しにトークンが必要です。上記の方法で発行してください。
- 署名不正は、トークンが別の
存在するはずの id が存在しないものとして読み取られる
- 原因:
memory.get_by_idのように組織全体の id だけで対象を指定する op は、id の存在を確認させてしまう 403 ではなく、行が存在しない場合と同じ応答を返します。通常の原因は、その行の名前空間に対する op のロールをトークンが持っていないことです。読み取りの前に id を解決する op も、呼び出し元が同じ id を持つ複数の名前空間に到達できる場合(namespace.restoreの後など)は、同様に応答します。ルールと例外は行スコープの操作を参照してください。 - 対処: その行の名前空間に対する op のロールを持つトークンを使用してください(トークンと権限付与)。複数の名前空間にまたがる id の場合は、その名前空間内のキーで行を指定してください(
memory.get、書き込みならmemory.update)。
スキーマとアップグレード
マイグレーションの保留またはチェックサムのずれ
- 症状:
/v1/healthがpending_migrationsを報告する、loom migrate --dry-run --strictが終了コード 1 で終了する(保留中のファイルだけでは終了コード 1 にならず、台帳にのみ存在する行やチェックサムのずれがある場合に終了コード 1 になります)、またはredeploy.shの事前チェックが停止する。 - 確認:
loom migrate --dry-run --strictは、保留中のファイルを表示し、続けてledger-onlyの行(リポジトリにはもう存在しない台帳上のファイル名)とchecksum drift(適用済みのファイルのうち、内容が記録された SHA-256 と一致しなくなったもの)を表示します。 -
対処:
- 保留中のファイル:
loom migrateを実行するか、LOOM_BOOT_MIGRATE=trueを指定して再起動します。 -
チェックサムのずれや ledger-only の行は、いずれかのサーバーが適用した後にマイグレーションファイルが変更された(または名前が変更されたうえで変更された)ことを意味します。多くの場合、マージされていないブランチから実行したサーバーが原因です。適用済みの DDL とリポジトリ内のファイルを比較してください。結果が同一であれば、現在のファイルを記録します(最も新しい行が優先されます)。
INSERT INTO loom._migrations (filename, checksum, applied_by) VALUES ('<file>', '<sha256 of the file>', 'operator');DDL が新しい名前で存在する ledger-only の行は、
DELETE FROM loom._migrations WHERE filename = '<old name>'で削除できます。
- 保留中のファイル:
リクエストが 503 SCHEMA_PENDING で失敗する
- 原因: ステートメントが、このビルドに含まれるマイグレーションによって作成されるテーブルを参照しているにもかかわらず、サービスがそのマイグレーションを適用していません(
LOOM_BOOT_MIGRATE=falseで起動したプロセス、またはマイグレーションの失敗)。 - 対処: 上記の保留中のマイグレーションの場合と同じです。
セル
LOOM_CELL が未設定のプロセスはゲートされる
- 症状: ヘルスプローブ以外のすべてのリクエストに 503 が返り、
/v1/health/readyのcellチェックが失敗し、ワーカーは1つも動作しません。理由には、デプロイメントが「is a cell in enforced mode and LOOM_CELL is unset」、「holds a partial cell state (... present)」、または「cell state is not read yet」であると示されます。org を宣言する CLI コマンドは、「this deployment is a cell in enforced mode (cell ...) and LOOM_CELL is unset」、「holds a partial cell state and LOOM_CELL is unset」、または「cell state could not be read (...)」というメッセージで拒否されます。最初のメッセージの場合は CLI にLOOM_CELLを設定してください。最後のメッセージの場合は、示されている理由に対処してください。つまり、不足している権限(アップグレードのステップ 15)か、応答しない Postgres です。 - 原因: Postgres をオーソリティとする構成では、すべてのサーバープロセスがデプロイメントのセルの状態(
loom.cell_first、loom.tenancy_mode、loom.cell_self、loom.tenancy)を読み取ります。LOOM_CELLが未設定の場合、プロセスがリクエストを処理できるのは、これらのいずれにも行がない間、または最初のセルの完全な状態をrecordingで保持している間だけです(セル)。 -
確認: ルーターのディレクトリにこのデプロイメントの行があるかどうかを確認します。ルーターのないデプロイメントでは省略してください。
LOOM_PG_DSNに対する psql セッションで開始します。SELECT deployment_id AS id FROM loom.authority \gset \connect '<router DSN>' SELECT cell, is_first, state, placed FROM loom_router.cells WHERE deployment_id = :'id';
- 対処(「not read yet」の場合):プロセスが Postgres マイグレーション未適用のまま(
LOOM_BOOT_MIGRATEが off)起動したか、それ以降 Postgres に到達していません。マイグレーションを適用する(/v1/healthに一覧が表示されます)か、接続を復旧してください。1秒以内に行われる次の読み取りで、以下のとおりプロセスが開放またはゲートされます。 -
対処(それ以外の場合):確認結果に応じて次のとおりです。
- デプロイメントがセルである場合(ディレクトリに行があり、後述の未接続の後続セルでも、切り戻し中の最初のセルでもない):
LOOM_CELLにセルの名前を設定します。部分的な状態の場合はloom cell prepareをもう一度実行すると完了します。 -
デプロイメントがセルとして意図されていない場合(ディレクトリに行がない、またはルーターがない)、または未接続の後続セル(行が
is_first = false、state = 'attaching'、placed = 0)を単一のデプロイメントに戻す場合:LOOM_PG_DSNに対する psql セッション(確認の後は\connectで戻ります)で、スキーマloomのテーブルを所有するロール(マイグレーションを行うロール。トリガーの変更にはテーブルの所有者が必要です)として、1つのトランザクションで状態をクリアします。その後、デプロイメントはopenになります。未接続の後続セルのディレクトリ行は、loom cell remove --cell <cell>で削除するまで有効なままです。デプロイメントを新たに prepare するにはこの削除が必要です。ロックの取得に失敗した場合は、psql がまだ開いていればROLLBACKし、ステップ全体をやり直してください。\set ON_ERROR_STOP on BEGIN; SET LOCAL lock_timeout = '100ms'; -- the attach lock: held by a running attach, prepare or update SELECT pg_advisory_xact_lock(7813586394088235880); SELECT pg_advisory_xact_lock(7813586394288842610); -- the migration lock ALTER TABLE loom.cell_first DISABLE TRIGGER cell_first_immutable; DELETE FROM loom.cell_first; DELETE FROM loom.tenancy_mode; DELETE FROM loom.cell_self; DELETE FROM loom.tenancy; ALTER TABLE loom.cell_first ENABLE ALWAYS TRIGGER cell_first_immutable; ALTER TABLE loom.cell_first ENABLE ALWAYS TRIGGER cell_first_no_truncate; COMMIT;次に、状態のトランザクションの後で(マイグレーションを行う起動の
ensureがトリガーを再作成しないように)、同じセッション・同じロールで org トリガーとloom.tenancyガードを削除します。ロックの取得に失敗した場合は、psql がまだ開いていればROLLBACKし、ステップをやり直してください。\set ON_ERROR_STOP on BEGIN; SET LOCAL lock_timeout = '100ms'; SELECT pg_advisory_xact_lock(7813586394288842610); -- the migration lock SELECT format('DROP TRIGGER %I ON loom.%I', t.tgname, c.relname) FROM pg_trigger t JOIN pg_class c ON c.oid = t.tgrelid JOIN pg_namespace n ON n.oid = c.relnamespace WHERE n.nspname = 'loom' AND t.tgname IN ('tenancy_insert', 'tenancy_update', 'tenancy_record') \gexec COMMIT;状態トランザクションの attach ロックでの失敗は、この Postgres に対して attach、prepare、update のいずれかが実行中であることを意味します。数時間かかることもあり、その間にステップをやり直しても同じように失敗します。ロックを保持しているセッションは次のクエリで特定できます。
SELECT a.pid, a.usename, a.application_name, a.client_addr, a.backend_start FROM pg_locks l JOIN pg_stat_activity a ON a.pid = l.pid WHERE l.locktype = 'advisory' AND l.granted AND l.classid = (7813586394088235880 >> 32)::oid AND l.objid = (7813586394088235880 & 4294967295)::oid AND l.objsubid = 1 AND l.database = (SELECT oid FROM pg_database WHERE datname = current_database());
- 切り戻し中の最初のセル(行が
is_first = true、state = 'attaching'、placed = 0で、modeは問いません。ステップ 3 のロックで拒否された attach はenforcedのまま残るためです。また、その Postgres でのSELECT mode FROM loom.tenancy_modeはrecordingを返します):次の順序で切り戻します。まずすべてのプロセスでLOOM_CELLを解除します。各プロセスはrecordingと同様に動作します。次に上記の状態トランザクションと削除ステップを実行します。その後、ルーターのオペレーター認証情報とセルのLOOM_PG_DSNを使ってloom cell remove --cell <cell>を実行します。このコマンドは、その Postgres がopenを示し、行のデプロイメント ID が記録されるまで拒否されます。行を先に削除すると、すべての新しい org に 503 が返ります。状態を先にクリアすると、LOOM_CELLが設定されたすべてのプロセスがゲートされます。ルーターはセルの Postgres を読み取れないため、ルーターで行を直接DELETEするとこの確認が省略されます。その場合、prepare 済みのままのセルは新しい org に 503 を返し続け、上記のステップを実行するまで再登録もできません。クリアしたストアにはセルの状態が残らず、デプロイメントはloom cell prepareからあらためて prepare します。行がplaced > 0の最初のセルは先へ進めるだけで、戻すことはできません。attach をもう一度実行してください(削除は拒否されます)。
- 別のデプロイメントに復元されたセルの Postgres のコピーは、元のセルのデプロイメント ID を引き継ぐため、確認クエリは稼働中の元のセルの行を返します。クリアしないでください。また、元のセルと並べて稼働させないでください。
- デプロイメントがセルである場合(ディレクトリに行があり、後述の未接続の後続セルでも、切り戻し中の最初のセルでもない):
LOOM_CELL を設定した CLI が、org を指定せずに書き込むコマンドを拒否する
- 症状: org を指定せずに書き込む、または取り消しを行うコマンド(
loom secrets reseal、loom settings set、loom ch-setup、loom revoke-tokenなど)が、「refusing: this Postgres's first row names cell ..., not LOOM_CELL=...」、「refusing: this cell's state could not be read (...)」、または「refusing: this ClickHouse could not be read for the cell check (...)」で終了します。 - 原因:
LOOM_CELLが設定されていると、このようなコマンドは何かを変更する前に、LOOM_PG_DSNからセルのfirst行を読み取り、その Postgres に照らして ClickHouse を確認します(セル)。first 行が別のセルを指している場合、CLI がそのセルのストアを向いていることを意味します。アクセスを元に戻せない取り消しは、Postgres の障害時でも実行され、セルを確認しなかったことが表示されます。 - 対処: 拒否メッセージが示す状態は別のセルのものなので、決してクリアしないでください。
LOOM_PG_DSNと ClickHouse の設定をこのセル自身のストアに向けるか、意図していたセルが first 行の示すセルであればLOOM_CELLをそのセルに設定してください。状態を読み取れなかった場合は、示されている理由に対処してください。つまり、不足している権限(アップグレードのステップ 15)か、応答しない Postgres または ClickHouse です。
起動時に「cell triggers: not applied」がログに出力される
- 症状:
open以外の状態のセルの起動時にcell triggers: not applied on loom.<table> (...)がログに出力され、loom doctorがそのテーブルのトリガーの欠落または無効化を示します(loom.cell_firstについてはどの状態でも、org テーブルのトリガーまたはloom.tenancyガードについてはenforcedの場合)。 - 原因: 起動時にセルの org トリガーとガードが作成され、
loom.cell_firstのトリガーが always に戻されます。このときロック待ちは1回あたり 100 ms で、1秒間隔で3回試行します。次の2つの場合には、そのテーブルを残したまま処理を続けます。1つは、テーブルがまだビジー状態の場合で、ログには競合するロックを保持または待機していたセッションが示されます。そのテーブルに対する長いトランザクションや一括書き込み、または autovacuum がその例です。短い試行では autovacuum を譲らせることはできず、完了するまで待つことになります(キャンセルできるほど長く待つと、そのテーブルへのすべての書き込みが起動の後ろで待たされます)。もう1つは、マイグレーションを行うロールがテーブルを所有していない場合で、ログにthis role cannot alter itと出力され、loom doctorはownerの不具合として示します。後続の起動でテーブルが完了するまで、テナンシーチェックを行わない書き込み元はそのテーブルで拒否されません。Loom 自身の書き込みには影響しません。 - 対処: ビジー状態のテーブルの場合は、ログに示されたトランザクションが古ければ終了させるか、autovacuum の完了(
pg_stat_progress_vacuum)を待ちます。ロールが変更できないテーブルの場合は、スキーマloomのテーブルを所有するロールとして起動するか、ALTER TABLE loom.<table> OWNER TO <role>でそのロールにテーブルを譲渡します。その後、LOOM_BOOT_MIGRATEを on にして1つの Pod を再起動し、loom doctorが欠落または無効のトリガーを示さなくなるまで繰り返します。
cell_marker のレディネスチェックがテナンシーマーカーを示す
- 症状:
LOOM_CELLを設定したプロセスの/v1/health/readyが、cell_markerチェックで「pooled Postgres sessions do not keep the tenancy marker」を報告します。enforcedまたはpartialのセルでは失敗し、まだrecordingの最初のセルでは同じ理由で成功し、プロセスのセルのハートビートはmarkedをfalseと報告します。 - 原因: プロセスと Postgres の間にコネクションプーラーがあります。プーラーは独自の起動パラメータでサーバー接続を開くため、それらの接続には
loom.tenancy_checkedがありません。クライアントのパラメータをSETで転送するプーラーも、リフレッシュがマーカーを読む前にRESET ALLを実行するため、マークなしと判定されます。セルに org トリガーが設定されると、そのようなセッションによる、セルが保持していない org への書き込みは、Loom 自身のものを含めてすべて拒否されます。 - 対処: セルの要件(Postgres)に従い、どのモードのプーラーも介さず
LOOM_PG_DSNを Postgres に直接向け、プロセスを再起動してください。LOOM_PG_DSNの変更には再起動が必要です。このチェックはセルのリフレッシュ(LOOM_TENANCY_MODE_CACHE_S)のたびに再度読み取られ、再起動後の最初のリフレッシュで解消されます。
起動が「function loom.tenancy_refuse_… does not exist」で失敗する
- 症状:
enforcedのセルでマイグレーションを行う起動が、セルのトリガーの作成中にfunction loom.tenancy_refuse_unheld() does not exist(または…_unmarked())で失敗し、loom doctorがどの状態でもその関数が存在しないことを示します。 - 原因: マイグレーションの実行後に、関数が手動で削除されました(org トリガーは 011、
loom.tenancyガードは 012 です。DROP FUNCTION … CASCADEは、そのトリガーも一緒に削除します)。マイグレーション台帳にはすでにそのファイルが記録されているため、どの起動でも関数は再作成されず、関数が戻るまでチェックされない書き込み元は拒否されません。新しいリリースのloom doctorが、そのリリースで最初にマイグレーションを行う起動の前に関数の不在を示した場合は、対処は不要です。その起動がファイルを実行します。 - 対処: スキーマ
loomのテーブルを所有するロールとして、psqlでマイグレーションファイル(schemas/pg_migrations/011_tenancy_triggers.sqlまたは012_tenancy_guard.sql)を実行します。その後、enforcedのセルではLOOM_BOOT_MIGRATEを on にして1つの Pod を再起動してください。その起動でトリガーが作成されます(ほかのセルでは、attach が後で作成します)。
セルではないデプロイメントで、書き込みが遅い、またはスクリプトが拒否される
- 症状: セルの状態が
open(すべてのプロセスが稼働)のデプロイメントで、Loom 自身の書き込みや、スクリプトまたは一括ローダーの書き込みが1行あたりに時間がかかる、loom.cell_firstに対するSELECT権限を持たないロールが「permission denied for table cell_first」を受け取る、あるいはスクリプトのloom.tenancyへの insert が SQLSTATELT001で失敗します。 - 原因: org トリガーがテーブルに残っています。prepare 済みのセルのスキーマのみの復元や、トリガーを削除するステップを省略したクリーンアップが原因です。
openではトリガーはすべての行を通しますが、マークのない書き込みのたびに状態が読み取られます。loom.tenancyガードのtenancy_recordは、スクリプトによるテナンシー行を SQLSTATELT001で拒否します。その行自体が状態をpartialにするためです。 -
確認:
SELECT c.relname, t.tgname FROM pg_trigger t JOIN pg_class c ON c.oid = t.tgrelid JOIN pg_namespace n ON n.oid = c.relnamespace WHERE n.nspname = 'loom' AND t.tgname IN ('tenancy_insert', 'tenancy_update', 'tenancy_record');
- 対処: スキーマ
loomのテーブルを所有するロールとして、LOOM_CELL が未設定のプロセスはゲートされるの削除ステップを実行してください。
ワーカー
ワーカーが毎回のパスで失敗する
- 症状:
loom.worker.consecutive_failuresが 3 以上のままになる。ワーカーのログに<name>: pass failedまたはpass exceeded its deadlineが繰り返し出力され、その後DEGRADEDと出力される。 - 確認: ワーカーの直近のエラーは
GET /v1/admin/workers.statusで、トレースバックはdocker logs loom-workers 2>&1 | grep -E '<name>: (pass|DEGRADED)'で確認する。 - 対処: 例外の内容に従って対処する。デッドラインによるキャンセルが繰り返される場合は、パスが実行間隔に対して大きすぎる(バックログが大きい、プロバイダが遅いなど)ことを意味する。プロバイダのエラーは、多くの場合キーの不足かクォータが原因である。フェイクプロバイダ上の LLM ワーカーについては、そのワーカーを無効にするか、実際のプロバイダを設定する。調査中に特定のワーカーだけを止めるには、そのフラグを false に設定してワーカーのコンテナを再作成する。他のワーカーは動き続ける。
ワーカーがまったく動かない
- 確認:
/v1/health?include=workersの各プロセスのworkers_leaderを見る。いずれか 1 つがリースを保持している必要がある。workers_lease_absentが warn の場合、有効なリースを保持しているプロセスがない。workers_lease_unreachableの問題は、プロセスが ClickHouse に問い合わせられなかった理由を示す。workers_lease_given_upは、そのワーカーの子プロセスが起動に失敗し続けたことを示す。 - 対処: すべてのレプリカを
LOOM_BACKGROUND_WORKERS=autoとLOOM_DEPLOYMENT=1で実行する。offのプロセスはワーカーを一切実行せず、デプロイメント外のプロセスもautoではワーカーを実行しない。onは、どのデプロイメントも使っていない ClickHouse に対してのみ設定する。この場合、プロセスは独自のコピーを実行し、リースを取得しない。アップグレード中は、古いビルドは有効な新しいビルドにリースを譲る。
ホスト
ホストまたは ClickHouse のディスクが不足する
- 症状: Loom ホストのディスクが満杯になる(コンテナが書き込みに失敗する、イメージのビルドが失敗する)、または ClickHouse が空き容量の不足を報告する。
- 確認: ホストでは
docker system dfとvar/code_reposのサイズを確認します。ClickHouse では、メンテナンスにあるテーブルごとのサイズとsystem.disksのクエリを確認します。ディスクが満杯の場合は、診断出力を/dev/shmに書き込んでください。 - 対処: Docker の JSON ログに上限を設定し、ビルドキャッシュと不要なイメージ(dangling image)を削除します(
docker builder prune、docker image prune)。停止中のコンテナをロールバック用に残している場合は、停止中のコンテナを prune しないでください。ClickHouse では、大量削除の後にマージでバージョンを集約させるか、loom code compact --applyでコードのベクトルテーブルをコンパクト化するか、テーブルごとの保持期間設定を有効にします。
ローカルスタック
- ダッシュボードが 503 を返す。 サーバーをソースから (
make server) 、ビルド済みのフロントエンドなしで実行しています。make frontend-buildを実行してください。/v1/admin/*はどちらの場合でも応答します。 - スタックが
.envを無視する。--env-file .envを付けずにdocker composeコマンドを実行すると、compose ファイルのフォールバック値(認証が有効、キーのない OpenAI プロバイダー)で起動します。make devを使うか、このフラグを渡してください。 - ソースから起動したサーバーが別のコードを実行している。 ローカル開発を参照してください。
クライアント、プラグイン、MCP
- コーディングエージェントのプラグインには、それぞれ症状別の表があります(Node が見つからないフック、primer がない、キャプチャが届かない、ツールが二重に表示される)。Claude Code と Codex を参照してください。プラグインの
loom-statusスキルは、Loom のチェックアウトなしでクライアントのチェックを実行します。 - リクエストに対応するレジャーの行がない。 リクエストが届いていません。
loom doctor --clientは、SDK とフックが解決するサーバー URL とトークン、およびそれぞれの取得元を示します。環境変数に古いLOOM_API_KEYやLOOM_BASE_URLが残っていると、~/.loom/よりも優先されます。トークンを付けたGET /v1/whoamiは、サーバーが検証したサブジェクト、組織、名前空間、ロールを返します。トークンに含まれない名前空間に対する 403 や、スコープ付きトークンでボディに名前空間がない場合のIDENTITY_INCOMPLETEは、バグではなく認可の結果です(トークンとグラント)。一時ディレクトリに残ったloom-flush-*.jsonファイルは、サーバーに届かなかったプラグインのキャプチャです(ヘッドレスボット)。 - MCP ツールが一覧に表示されない。 一覧は、呼び出し元ではなく MCP URL の
?toolset=によって変わります。allでは、コアにもアトミックなロスターにも含まれない実験的な op は一覧から除外されますが、名前を指定するかloom_opを通じて呼び出せます。code.*ツールがデフォルトのツールセットに表示されるのは、LOOM_MCP_CODE_TOOLS=trueの場合のみです(MCP ツールセット)。 - MCP 呼び出しが
isError: trueを返す。 401 以外の拒否(LOCKED、PINNED_CONFLICT、BLACKLISTED、RATE_LIMITED、UNKNOWN_ARGUMENTなど)は、isErrorを持つツール結果として返され、HTTP エラーの詳細はstructuredContentに入ります。401 や 5xx は JSON-RPC エラーです。判別にはcodeを使ってください。 - 送信したフィールドが無視された。 レスポンスの
ignored_argsにそのフィールドが示され、近い既知のフィールドがある場合はdid_you_meanも付きます。書き込み操作では、近いスペルミスは 422UNKNOWN_ARGUMENTで拒否されます(不明なフィールドと削除されたフィールド)。 - 429
RATE_LIMITED。 バケットについてはモニタリングを参照してください。再試行できる時刻はRetry-Afterが示します。
バグの報告
loom report は、バグ報告フォームの Environment フィールドに入力する内容を loom doctor の診断結果として出力します(出力されるのは有無を示す真偽値のみで、シークレットの値は一切含まれません)。--open を指定すると、バージョン情報が入力済みのバグ報告フォームが開きます(issue の報告)。