トラブルシューティング¶
このドキュメントでは、OWL CLI および OWL MCP Server の一般的な接続問題を扱います。
v1.9.0:DPoP ログインとアップグレード¶
invalid_grant は一時コードが無効、期限切れ、または使用済みであることを示します。Studio で新しいコードを生成してください。invalid_token は認証情報が無効であることを示します。新しいコードで owl login --dpop を実行してください。invalid_dpop_proof の場合は、ローカルマシンの時計、サイトの HTTPS アドレス、および Registry の Ingress 設定を確認してください。CLI は有効な新しい nonce challenge を処理します。認証失敗を理由に書き込み操作を自動的にリプレイしないでください。
profile add で引き続き API Key の入力を求められる場合は、先に CLI をアップグレードし、owl profile add --help に Studio temporary code (DPoP) が含まれていることを確認してください。旧スクリプトは、OWL_TEMP_CODE 経由で一時コードを提供するように変更してください。アカウントの追加にはネットワーク接続が必要で、切り替えではローカル設定のみを確認します。
owl sync が成功すると、ツールカタログを取得済みであることを示します。owl config show でログイン状態を確認し、現在のアカウントに権限がある読み取り専用ツールを 1 つ呼び出して、アクセスが可能であることを確認してください。複数の Profile の使用。
v1.7.0:アップグレードと呼び出し結果¶
- DQL が失敗した場合は、
query_text、raw_output、およびissues[].messageで具体的な原因と利用可能な行・列情報を確認してください。time.validation_unavailableはバリデータが利用できないことを示しており、クエリ構文エラーとして扱わないでください。診断内容を共有する前に、その中の元のクエリ内容を確認してください。 - ドキュメントのバージョンが変わった後は再検索し、新しい
read_referenceを使用してください。Registry のファイルシステムにはアクセスしないでください。DQL 本文の読み取りを参照してください。 - 実行時モードで設定または Profile 操作が拒否された場合は、実行環境側で 3 つの実行時変数がセットで注入されているかを確認してください。アイデンティティを切り替えて回避しないでください。実行時 Profileを参照してください。
- カタログ書き込みが pending であるか、監査が不確定な場合は、書き込み結果と確認フローに従って処理し、新しい UUID を生成して重複書き込みしないでください。
v1.6.0:時間検証または同期の失敗¶
時間エラーは issues[].code で区別できます。time.unit ではタイムスタンプの単位と整数型を確認し、time.pair では対になるパラメータを補完し、time.order では前後順序を修正し、time.span では上限を超えたウィンドウを縮小します。DQL の相対ウィンドウまたは競合するウィンドウは、削除するか、外部範囲と一致する絶対ウィンドウに変更してください。time.validation_unavailable の場合は Registry の dqlcheck を確認してから、事前検証を再試行してください。
owl sync はいずれかのカテゴリのダウンロードが失敗すると失敗を返し、失敗したカテゴリの既存キャッシュとローカルバージョンを保持します。初回の自動同期が失敗すると後続の実行がブロックされます。キャッシュ期限切れ後の自動同期が失敗した場合も、従来の動作どおり警告を出し、既存のキャッシュを使用します。
CLI:owl が見つからない場合¶
現象:
処理方式:
- Windows:現在の PowerShell を閉じ、再度開いてから実行してください
- Linux / macOS:現在のターミナルウィンドウを閉じ、再度開いてから実行してください
- 実行ファイルがデフォルトのインストールディレクトリに存在するか確認してください
デフォルトの実行ファイルパス:
- Windows:
%LOCALAPPDATA%\Programs\owl\owl.exe - Linux / macOS:
$HOME/.local/bin/owl、書き込み不可の場合は/usr/local/bin/owlにフォールバックします
CLI:過去のテストバージョンのアップグレードに失敗する¶
owl --version に testing-<SHA> が表示される場合は、現在の更新チャネルで新しいインストールスクリプトが提供されていることを確認してから、owl update を実行してください。新しいスクリプトは、このような過去のビルドを現在設定されているチャネルの正式バージョンへ移行できます。先に CLI を交換したり、チャネルを切り替えたりする必要はありません。
引き続き failed to parse local owl version または failed to read local owl version が表示される場合は、owl --version が正常に実行できるか、およびバージョンがサポート対象の正式バージョン、または testing- に 7~40 桁の 16 進数 Git SHA を付けた形式であるかを確認してください。不明、破損、または実行に失敗したバージョンは、旧バージョンとして強制的に上書きされません。原因を確認した後、手動インストールを参照して再インストールできます。
Agent での CLI と Skill の問題¶
| 現象 | 確認と対処 |
|---|---|
ローカルターミナルでは owl を実行できるが、Agent がコマンドを見つけられない |
Agent の実行環境で owl --help を確認させます。リモート開発環境やコンテナはローカルとインストールを共有しないため、実際の実行環境に CLI をインストールし、その環境の PATH を更新する必要があります |
| CLI は利用できるが、対応する Skill が認識されない | Agent に、owl-diagnostics が現在の製品で認識される場所にインストールされているかを確認させます。製品の案内に従って更新するか、新しいセッションを作成してください。共通 Skill インストールプロンプトを再送信できます |
| Agent がコマンドを示すだけで、実際には実行しない | 現在、ターミナル実行機能を備えた Agent モードを使用しており、必要な権限が付与されていることを確認したうえで、読み取り専用呼び出しを 1 回実行するよう明確に指示してください |
| Agent を切り替えた後、クエリ対象のワークスペースが正しくない | 新しい Agent の実行環境で現在の Profile と Endpoint を確認してください。別のターミナルの環境変数や設定がすでに有効になっていると想定しないでください |
CLI が実行できること、Skill が認識されること、業務呼び出しが成功することは、3 つの異なる確認項目です。最終的には初回呼び出しの検証に従って、実際の返却結果を確認してください。
自動インストール:AI ツールがコマンドを実行できない¶
原因:現在の AI ツールにターミナルコマンドの実行権限がないか、現在の環境でローカル設定への書き込みが禁止されています。
処理方式:
- ターミナルコマンドの実行をサポートする AI ツールに切り替えてください
- または 手動インストールに切り替えてください
自動インストール:一時認証情報が無効、期限切れ、または未承認¶
原因:OWL_TEMP_CODE が期限切れ、使用済み、コピーミスであるか、現在のアカウントに認証コードを生成する権限がありません。
処理方式:
- Guance コンソールで一時認証情報を再生成してください
- 自動インストールのインストールコマンドを再実行してください
- 使用済みの
OWL_TEMP_CODEを再利用しないでください
自動インストール:Endpoint の不一致¶
原因:OWL_REGISTRY_ENDPOINT がワークスペースの所在するサイトと一致していないか、誤って /api/v1 を結合しています。
処理方式:
- ワークスペースの所在するノードに応じて OWL CLI Endpoint を再選択してください
OWL_REGISTRY_ENDPOINTには Endpoint のルートアドレスのみを入力してください- プライベートデプロイ環境では、実際のデプロイで提供される OWL CLI Endpoint を使用してください
CLI:認証失敗または Endpoint にアクセスできない¶
まず、実際に有効なアイデンティティと設定ソースを確認します:
Profile を選択した後(default を含む)、Endpoint/Key のセット全体はその Profile から取得されるため、OWL_REGISTRY_ENDPOINT、OWL_API_KEY、または OWL_TOKEN を変更しても上書きされません。これらの環境変数が設定ファイルを上書きするのは、旧設定モードまたは --conf を単独で使用する場合のみです。
以下を確認してください:
- 現在有効な Endpoint が、ワークスペースの所属するサイトの OWL CLI Endpoint であるか
- Endpoint に誤って
/api/v1が結合されていないか - 選択した Profile のアクセストークンが有効であるか。環境変数による上書きが適用されるシナリオでは、
OWL_API_KEYとOWL_TOKENが同時に設定されている場合、OWL_API_KEYが優先されます - API Key に対応する Open API 権限があるか
- 現在のターミナルから OWL CLI Endpoint にアクセスできるか
CLI:誤った Profile を選択している¶
owl profile list と owl profile current -f json を使用して、ローカルエイリアス、永続化されたデフォルト、および実際の選択を確認してください。選択の優先順位は --profile > OWL_PROFILE > owl switch で保存されたデフォルトです。Profile を追加しても切り替えは行われません。--profile は今回のコマンドにのみ影響します。
owl --profile customer-a config show
owl --profile customer-a sync
owl --profile customer-a exec owl.data.show_dql_namespace
Profile を選択した後、Endpoint と認証情報はその Profile から取得され、アイデンティティ環境変数では上書きされません。アイデンティティ以外の環境設定は引き続き有効です。OWL_PROFILE が設定されている場合は、その変数を解除してからでないと owl switch を実行できません。リクエストが失敗しても、自動的に別の Profile に切り替わることはありません。 B を追加した後も、デフォルトアカウントは A のままです。--profile customer-b は今回のコマンドに対してのみ B を選択します。owl switch customer-b を実行すると、以降のコマンドで B を使用できます。アカウントの追加にはオンラインで一時コードを引き換える必要があり、切り替えではローカル設定のみを確認します。
CLI:profile remove --purge のクリーンアップに失敗する¶
エラーで示された管理対象ディレクトリの権限を確認し、権限を修正してから削除を再試行してください。アーティファクトのクリーンアップに失敗した場合、設定と認証情報は保持され、エイリアスは復元されます。一部のキャッシュやクエリファイルはすでに削除されている可能性があります。アーティファクトを保持する必要がある場合は、--purge を付けずに owl profile remove <alias> を使用してください。
CLI:HTTPS 証明書の検証に失敗する¶
ローカル開発環境またはプライベートテスト環境で自己署名証明書を使用している場合、CLI が x509: certificate signed by unknown authority を返すことがあります。まずシステムに信頼できる CA をインストールしてください。どうしてもインストールできない場合は、一時的に次のコマンドを実行できます:
この設定は Registry のアイデンティティ検証を無効にするため、中間者攻撃を受ける可能性があります。制御された開発環境でのみ使用し、本番環境では有効にしないでください。検証を元に戻すには、owl config set registry.insecure_skip_verify false を実行します。
CLI:長時間実行されるクエリが早期にタイムアウトする¶
データクエリが context deadline exceeded を返す場合は、まずネットワークと Registry の状態を確認し、次に registry.request_timeout を確認してください。この値の単位はミリ秒で、デフォルトは 150000 です。データクエリツールのサーバー側期限は 130 秒です。クライアントの総タイムアウトをより短く設定することは推奨しません。
クライアントのタイムアウトを増やしても、サーバー側のクエリ期限は延長されません。クエリが引き続き失敗する場合は、時間範囲を狭めるか、返却量を減らすか、クエリ条件を簡素化してください。
CLI:tool not found が表示される¶
原因:ローカルキャッシュにそのツールが存在しないか、ツール名が間違っています。
各 Profile のツールキャッシュは独立しています。Profile、Endpoint、または Key を切り替えた後は、同じ Profile で owl sync を実行してください。
処理方式:
ツール名を確認してから再実行してください。
CLI:category not found が表示される¶
原因:カテゴリ名が存在しないか、まだ同期されていません。
処理方式:
CLI:missing required parameter が表示される¶
原因:必須パラメータが不足しています。
処理方式:
ツール定義に従って必須パラメータを補完してから再実行してください。
CLI:unknown parameter が表示される¶
原因:パラメータ名がツール定義と一致していません。
処理方式:
パラメータ名を確認してから再実行してください。
CLI:owl validate が検証失敗を返す¶
owl validate は事前検証のみを実行し、対象ツールを呼び出しません。JSON 結果の request_executed は常に false である必要があります。
まず、検証に合格しなかった結果と、検証コマンド自体の失敗を区別します:
- JSON に
valid: falseが含まれる場合は、ツールを実行しないでください。issuesのkindとcodeに基づいてパラメータを修正してください。 - コマンドが非 0 のステータスコードで終了した場合、または検証の JSON 結果が出力されなかった場合は、検証が完了していないことを示します。ツールを実行しないでください。同期、認証、ネットワーク、または Registry の可用性を確認した後、再度検証を実行してください。
valid: false の結果については、issues の kind と code に基づいて対処します:
tool/tool_not_found:まずowl syncを実行し、ツール名がowl listの出力と完全に一致することを確認してください。parameter/invalid_arguments:問題リストに基づいて、不足パラメータ、誤った型、または未知のパラメータを一度に修正してください。dql_syntax/dql.parseError:owl.data.queryのquery_textを修正してください。generated_dql/dql.builderError:simple query のselect_clause、where_clause、またはgroup_by_clauseを修正してください。同じパラメータで直接再試行しないでください。
validate コマンドがないと表示される場合は、1.2.0 以降にアップグレードしてください。simple query で DQL を生成するための事前検証には、1.2.1 以降が必要です。
CLI:結果が空または想定と異なる¶
以下の順序で確認してください:
owl show <工具名>を使用してパラメータ定義を確認してくださいowl list -c <分类ID>を使用して、正しいツールを実行していることを確認してくださいowl syncを使用してローカルキャッシュを更新してください- クエリの時間範囲が正しいか確認してください。時間パラメータは 13 桁のミリ秒タイムスタンプである必要があります
- API Key に対応するリソースの Open API 権限があるか確認してください
MCP:クライアントの接続に失敗する¶
以下を確認してください:
- MCP タイプが
streamableHttpに設定されているか - URL が現在のサイトの OWL MCP Endpoint であるか
- URL が
/mcpで終わっているか - リクエストヘッダーに
Authorization: Bearer <API Key>が含まれているか - クライアントのネットワークから OWL MCP Endpoint にアクセスできるか
MCP:認証に失敗する¶
以下を確認してください:
- API Key が正しくコピーされているか
- Authorization Header の形式が正しいか
- API Key が無効化、削除、またはローテーションされていないか
- API Key が属するワークスペースが、現在アクセス対象のワークスペースであるか
リクエストヘッダーの形式:
説明:
/mcpエンドポイントは、イベントストリームを確立する前に認証を行います。認証情報がないか無効な場合は、text/event-streamイベントストリームを開始せず、HTTP401 Unauthorizedを直接返します(WWW-Authenticate: Bearer realm="mcp"レスポンスヘッダー付き)。そのため、クライアントが「接続済みだがイベントストリームが空」と報告した場合は、実際に 401 を受信していないかを優先的に確認してください。これは通常、空のストリームではなく認証の問題です。401 とWWW-Authenticateヘッダーに基づいて認証情報を修正し、再試行してください。
MCP:ツールリストが空¶
考えられる原因:
- MCP クライアントがサービスへの接続に成功していない
- API Key が無効、または権限が不足している
- クライアントが MCP ツールリストを更新していない
- Endpoint の選択が誤っている
処理方式:
- クライアントで MCP 接続を再テストする
- Endpoint がワークスペースのサイトと一致することを確認する
- Authorization Header が正しいことを確認する
- MCP クライアントを再読み込みするか、再起動する
MCP:ツール呼び出しが権限エラーを返す¶
原因:API Key に対応する Open API 権限がありません。
処理方式:
- API Key の権限範囲を確認してください
- 読み取り専用のシナリオには、対応するクエリ権限を付与してください
- 書き込みシナリオには、対応する書き込み権限を付与してください
- Agent に過度に広い API Key 権限を直接設定することは推奨しません
MCP:ツール呼び出しが空の結果を返す¶
以下の順序で確認してください:
- クエリの時間範囲が正しいか
- 選択したデータドメイン、source、field、index が存在するか
- 先に探索系ツール(例:
owl.metric.list、owl.log_index.list)を呼び出す必要があるか - API Key にそのデータ範囲の読み取り権限があるか
- 現在のワークスペースに対応するデータが実際に存在するか
MCP:書き込み操作がブロックされる、または反映されない¶
考えられる原因:
- API Key に書き込み権限がない
- クライアントで人手による確認が設定されているが、確認されていない
- パラメータ構造がツールの要件を満たしていない
- ワークスペース側に承認または監査の制限がある
処理方式:
- ツールのパラメータを確認する
- API Key の権限を確認する
- クライアントが人手による確認を待機しているか確認する
- ワークスペース側の承認、監査、または権限設定を確認する