troubleshoot-ngrok について
troubleshoot-ngrokは、ngrokのエンドポイントやエージェントの障害を診断するスキルです。エラーコード、その説明ドキュメント、稼働状態を順に確認し、MCP、シェル、ローカルの検査手段で原因を絞り込みます。
主な機能
- 01出力やページからエラーコードを取得
- 02コード固有のドキュメントを確認
- 03エンドポイント、エージェント、通信状態を確認
- 04Traffic Policyを検証
- 05コードのない症状を調査
- 06失敗したリクエストを再試行して修正を確認
活用シーン
- 01オフラインや上流接続失敗の診断
- 02エージェントの接続状態とバージョンの確認
- 03リクエスト失敗の原因特定
- 04ポリシー無効やTLSエラーの調査
MCP 対応
ngrok MCPサーバーを使い、エラー文書、エンドポイント、エージェント、トラフィック検査、接続、アカウント制限、ポリシー検証のツールを利用します。サーバーがない場合は、エージェント出力、ローカル検査ツール、ダッシュボードを使います。
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/ / github.com/ ngrok/ skills --skill troubleshoot-ngrokインストール後、Claude Code で/troubleshoot-ngrokを入力して読み込まれたか確認します。
詳細
ngrok のトラブルシューティング
エラーを取得し、ドキュメントページを読み、ライブ状態を確認して該当する原因を特定するという 3 つの手順で、失敗している ngrok エンドポイントまたはエージェントを診断します。
1. エラーを取得する
ngrok のエラーには ERR_NGROK_<code> コードが含まれます。このコードは、ブラウザーのエラーページ、エージェントの出力、API のレスポンス、トラフィックインスペクターに表示されます。コードには数値のもの(ERR_NGROK_8012)と名前のもの(ERR_NGROK_AGENT_NOT_FOUND)があります。
コードを取得してください。ユーザーがメッセージしか持っていない場合は、値を含めて正確なテキストをそのまま使用してください。エラーがまったくない場合は、症状別に進んでください。
2. エラーのドキュメントページを読む
各コードには、原因と解決方法を記載したページがあります。コードを記憶に頼って説明しないでください。コードごとに内容が異なるため、推測が少しでも違うと、ユーザーを誤った方向へ導いてしまいます。
docs_get_errorを備えた ngrok MCP サーバーの場合:codeを指定して呼び出してください。コードがない場合はmessageを指定します。1 つのメッセージに対して複数のコードが返された場合は、ユーザーにコードを確認してください。1 つを選ばないでください。- それ以外の場合: メッセージしかない場合は、エラーページまたはエージェントの出力からコードを取得するか、ユーザーに確認してください。メッセージからコードを推測しないでください。コードがわかったら、コードを小文字にし、
ERR_NGROK_の接頭辞を除いてhttps://ngrok.com/docs/errors/err_ngrok_<code>.mdを取得してください。たとえば、ERR_NGROK_8012はerr_ngrok_8012.mdです。404 が返された場合はコードが間違っています。ユーザーに確認してください。
docs_search ではエラーページを見つけられません。エラーコードの検索には使用しないでください。
3. 該当する原因を特定する
エラーページには、考えられる原因が記載されています。ユーザーにそれぞれ確認してもらうのではなく、アカウントを調べて該当する原因を特定してください。
ngrok MCP サーバーがある場合:
| 質問 | ツール |
|---|---|
| この URL で何かが稼働していますか? | URL を指定して get_resource を実行します。gw_list_endpoints でアカウントが提供しているエンドポイントを確認できます。わずかに異なる URL はよくある原因です。 |
| エージェントは接続されていますか?バージョンは最新ですか? | gw_list_agents:接続済みエージェント、バージョン、非推奨化の期限を確認できます。 |
| このリクエストで何が起きましたか? | ngrok のエラーページに記載されたリクエスト ID を指定して gw_get_traffic_inspector_request を実行します。 |
| どのリクエストが失敗しましたか? | gw_query_traffic_inspector:各行に ngrok のエラーコードが含まれます。ホスト、ステータス、パスで絞り込めます。 |
| TCP または TLS エンドポイントの障害ですか? | gw_query_connections(エラーコードで絞り込めます)を実行し、続けて gw_get_connection を実行します。 |
| アカウントが制限に達していますか? | platform_get_enforced_limits を実行します。platform_get_usage が報告するのは使用量であり、上限ではありません。 |
| Traffic Policy は有効ですか? | gw_validate_traffic_policy は、各問題の行番号と列番号を報告します。 |
サーバーがない場合は、エージェント自体の出力(ngrok http <port> --log stdout)、ローカルインスペクター(http://localhost:4040)、ダッシュボードを使用してください。
その後、ページに記載された修正を適用し、失敗したリクエストを再送して確認してください。
よくあるコードについてのメモ
詳しい修正方法はドキュメントページを参照してください。以下は、ページに記載されていない補足です。
- ERR_NGROK_3200(エンドポイントがオフライン)。 アクセスした URL で何も稼働していません。次の 2 点を確認してください。エージェントが接続されているか、そのエージェントがこの URL と 完全に同じ URL を提供しているかです。サブドメインが異なる場合や、入力ミスがある場合も同じエラーになります。訪問者が 3200 を報告した場合、通常は所有者のエージェントが停止しています。訪問者側でできることはないかもしれません。
- ERR_NGROK_8012(アップストリームへの接続に失敗)。 ngrok は動作していますが、ローカルサービスが応答していません。サービスが、エージェントの転送先とまったく同じポートおよびスキーム(
httpとhttps、localhostと127.0.0.1とコンテナーアドレスの違い)で実行されていることを確認してください。 - 認証エラー(例:ERR_NGROK_4018)。認証情報がないか、無効です。まず、どの認証情報が使われているか確認してください。エージェントは authtoken を、API と IaC は API キーを使用します。
ngrok-setupに引き継いでください。 - セッション制限(例:ERR_NGROK_108)。同じアカウントの別のエージェントがすでに接続されています。
gw_list_agentsで実行場所を確認できます。
症状別(エラーなし)
- localhost では動作するが、ngrok URL 経由では 400 エラーになる、または拒否される。 アプリまたは開発サーバーが ngrok の
Hostヘッダーを拒否しています。expose-localhost/references/TROUBLESHOOTING.mdを参照してください。内部エンドポイントの場合は、--host-header=rewriteを指定します(run-mcp-gatewayを参照)。 - エージェントが起動直後に終了する。 認証情報の問題(
ngrok-setupを参照)か、解析できない設定ファイルが原因です。ngrok config checkを実行してください。 - Traffic Policy が効かない。 ポリシーがアクセス先のエンドポイントに適用されていないか、それより前のルールでチェーンが終了しています。ユーザーの画面で適用状況を確認してください(
ngrok-surfacesを参照)。ルールの順序についてはngrok-engineを参照してください。 - ngrok ドメインで TLS または証明書のエラーが発生する。 まず status.ngrok.com で障害情報を確認してください。障害がなければ、ユーザーのネットワーク上にあるものが TLS を傍受している可能性があります。ISP のフィルター、VPN、または管理対象端末のエンドポイントセキュリティソフトウェアなどです。ユーザーに別のネットワークを試してもらい、
openssl s_client -connect <host>:443 -servername <host>で証明書の発行者を比較してもらってください。
エージェント向けの注意事項
- MCP サーバーまたはシェルを利用できる場合は、自分で確認を実行してください。確認項目の一覧ではなく、原因と修正方法をユーザーに伝えてください。
- コードに基づいて対応してください。コードに原因が示されている場合は、憶測で別の原因を探さないでください。
- 原因が認証情報またはポリシーの場合は、
ngrok-setupまたはngrok-engineに引き継いでください。ここでその内容を繰り返さないでください。