トラブルシューティング

This page is not available in the language you requested. You have been redirected to the English version of the page.
Link to this page copied to clipboard
Not for use with personal data

このページは、両方のDocker および npm ディストリビューションに共通する問題を扱っています。どちらか一方のディストリビューションにのみ適用される問題は、それに応じてラベルが付けられています。

サーバーが起動しない

  • Docker が実行中（Docker ディストリビューションの場合）、または Chromium がインストールされているか確認してください（npm ディストリビューションの場合 — Chromium インストールを参照）。
  • あなたのAXE_API_KEYまたはAXE_ACCESS_TOKENが正しいことを確認してください。ただし、両方設定しないでください（両方が設定されていると、サーバーは起動時に失敗します）。
  • axe MCP サーバーにアクセスできることを確認してください（必要に応じてサポートに連絡してください）。

スキャンタイムアウト

  • 複雑なページの場合はBROWSER_TIMEOUT_MSを増やしてください。
  • ターゲット URL がネットワークからアクセス可能であることを確認してください。
  • ネットワーク接続性の問題を確認してください。

ローカル開発サーバーのスキャンがERR_CONNECTION_REFUSEDで失敗する

これはDocker ディストリビューションに適用されます — npm ディストリビューションでは、サーバーはホスト上で直接動作し、localhostサービスに通常通りアクセスできます。

analyzeツールが、ローカルで実行中の開発サーバーをスキャンしようとしてnet::ERR_CONNECTION_REFUSEDエラーで失敗する場合、これはおそらく、axe MCP サーバーが Docker コンテナ内で実行され、ホストマシン上のlocalhost（つまり127.0.0.1）にのみバインドされたサービスにアクセスできないためです。

エラー例：

net::ERR_CONNECTION_REFUSED at http://192.168.65.2:5173/

解決策： Start your dev server with the --host flag set to 0.0.0.0 so it listens on all network interfaces, making it reachable from within the Docker container:

# Vite
npm run dev -- --host=0.0.0.0

# Webpack (webpack-dev-server)
npm run dev -- --host=0.0.0.0

高度なルールが実行されませんでした

まず、advancedRulesブロックをanalyzeレスポンスで確認してください — sourceフィールドが理由を示します。

source 対処方法
org_default 何も問題はありません。valueがdisabledである場合、管理者がaxe 設定でそれを組織のデフォルトとして設定しています。
org_policy_locked 管理者が設定をロックしています。設計上、上書きは無視されます — 彼らに「ユーザーによる変更を許可」を確認するよう依頼してください。
unavailable このサーバーでは高度なルールが利用できないか、またはaxe 設定がそれらに対して利用可能な値を返しませんでした。

他に確認すべきこと：

  • advancedRulesパラメータがエージェントによって提供されていません。analyzeツールは、高度なルールが組織に利用可能な場合にのみ提供します。アクセスの変更後にクライアントがツールリストを再読み込みするようにMCPサーバー接続を再起動してください。
  • AXE_ADVANCED_RULESに効果がありませんでした。サーバーが実際にそれで起動したことを確認してください（入力ミスは起動に失敗します — AXE_ADVANCED_RULESを参照）。また、advancedRules引数が優先されていないことを確認してください。
  • dataから高度な調査結果が欠落しています。 必要なレビューに劣化した高度な調査結果は、デフォルトの確認が必要がaxe 設定で有効になっていない限りフィルタリングされます。レスポンスのmessages配列で劣化メッセージを確認してください。
  • 高度なルールを有効化すると、スキャンがタイムアウトします。 それらはスキャンごとにおよそ15〜20秒追加されます。BROWSER_TIMEOUT_MSを引き上げてください。
  • 高度なルールがセッション中に停止しました。 Dequeが高度なルールが組織に利用できないためスキャンを拒否する場合、そのプロセスの残りの間、サーバーはそれを試みるのを停止します。サブスクリプションの変更後に再起動してください。

完全なリファレンスを見るには高度なルールをご覧ください。

Docker に関する問題

  • Docker デーモンが実行されていることを確認してください。
  • Docker の権限を確認してください。
  • Docker イメージのダウンロードのためのネットワーク接続性を確認してください。
  • Docker に十分なメモリがあることをdocker system pruneを実行して確認してください。

Chromium インストール（npm）

このセクションは、npm ディストリビューションに適用されます。Docker ディストリビューションは独自のブラウザをバンドルしているため、Docker ユーザーは Chromium をインストールする必要がなく、ここで説明されるエラーの影響を受けません。

エラーの意味

axe MCP サーバーはPlaywrightを通じて実際のブラウザを操作してアクセシビリティスキャンを実行します。npm ディストリビューションの場合、そのブラウザ（Chromium）はホストにインストールされている必要があります。欠落している場合、またはインストールされているバージョンがサーバーでシップされる Playwright バージョンの Chromium リビジョンと一致しない場合、Chromium が起動できなかったというエラーでサーバーは起動に失敗します（または最初のスキャンで失敗します）。

これは新規インストール時に予想されるもので、簡単に修正できます。

標準的な修正

tip

エラーメッセージが最も信頼できる情報源です。 それは実行中のサーバーに対する正確な固定コマンド名を示します — そのまま実行してください。以下のコマンドは、最新の公開リリースから同じピンを導出します。これが正しいです、ただし古いaxe-mcp-serverに固定されている場合を除きます。

axe MCPサーバーが提供するPlaywrightバージョンに一致するChromiumリビジョンをインストールしてください。Playwrightは固定される必要がありますので、単なるnpx playwrightではサーバーがサポートしないChromiumリビジョンの新しいリリースに解決しません：

npx playwright@$(npm view axe-mcp-server dependencies.playwright) install chromium

その後、MCP サーバー（または MCP クライアント）を再起動して、再試行してください。

固定された古いサーバーを実行する場合、そのバージョン—npm view axe-mcp-server@<version> dependencies.playwright—を代用するか、エラーメッセージからピンを取得してください。執筆時点では、サーバーバージョン1.4.0がPlaywright 1.61.1を提供しています。

Windowscmd.exe上では、$(...)代替がないため、npm view axe-mcp-server dependencies.playwrightを別々に実行してバージョンを貼り付けてください。PowerShell、Git Bash、およびWSLはコマンドをそのまま処理します。

Linux のフォローアップ

Linux では、Chromium も存在しないかもしれない多数のシステムライブラリに依存しています。標準の修正後もブラウザーが起動しない場合は、それらの依存関係をインストールしてください:

sudo npx playwright@$(npm view axe-mcp-server dependencies.playwright) install-deps chromium

これらの手順を 1 つのコマンドに組み合わせることもできます:

sudo npx playwright@$(npm view axe-mcp-server dependencies.playwright) install --with-deps chromium

既にお持ちのブラウザを使用する

対応する Chrome/Chromium バイナリがホストにすでにある場合、AXE_CHROME_PATH環境変数をそのバイナリに設定することで Playwright のインストール全体をスキップできます。これは、Playwright のダウンロードがブロックされている（制限されたネットワーク、プロキシ）場合や、システム依存のインストールがオプションではない場合に、最も迅速な解決策になることが多いです。要件についてはAXE_CHROME_PATHを参照してください — ブランド付き Google Chrome デスクトップ版 137+ はサポートされておらず、値は.appバンドルではなく実行可能なバイナリである必要があります。

なぜ Chromium がバンドルされないのか

Playwright は各 Playwright バージョンに特定の Chromium リビジョンを固定し、そのリビジョンは時間と共に変化します。ブラウザバイナリを npm パッケージにバンドルすると、サイズが大幅に増加し、パッケージが1つのプラットフォームのバイナリに縛られ、Playwright が固定リビジョンを更新するとすぐに陳腐化します。 代わりに Playwright 経由で Chromium をインストールすると、インストールされたバージョンが期待する正確なリビジョンを、対象プラットフォームに対して入手できることが保証されます。（Docker ディストリビューションは、既知の単一環境用にビルドされるため、ブラウザをバンドルできます。）

axe-mcp-server のアップグレード後の再実行

axe-mcp-serverをアップグレードすると、現在インストールされているものより新しい新しい Chromium リビジョンを固定する新しい Playwright バージョンが含まれる可能性があります。そのような場合、アップグレード後に同じ起動エラーが再び発生する可能性があります。 修正方法は同じで、アップグレードされたサーバーでシップする Playwright バージョンを使用してインストールを再実行し、Chromium が一致するようにします。

npx playwright@$(npm view axe-mcp-server dependencies.playwright) install chromium

ピンはハードコーディングされるよりも派生されるため、アップグレードを繰り返してもコマンドは正しいままです。axe-mcp-serverをアップグレードしてサーバーが起動時にChromiumの不一致を報告するたびに再実行してください。

認証エラー

API キー

  • API キーが有効で期限切れでないことを確認してください
  • axe アカウントポータルのサブスクリプションに MCP サーバーアクセスが含まれていることを確認してください
  • API キーが「axe MCP Server」製品用に作成されたものであることを確認してください
  • AXE_API_KEYだけが設定されていることを確認してください — AXE_ACCESS_TOKENも設定されている場合、サーバーは起動時に失敗します
  • あなたの axe サーバーの URL が正しいことを確認してください — 組織が地域、プライベートクラウド、またはオンプレミスの axe インスタンスを使用している場合、AXE_SERVER_URLはインスタンスのベース URL に設定されている必要があります。詳細は設定リファレンスを参照してください。

OAuth

  • AXE_ACCESS_TOKENだけが設定されていることを確認してください — AXE_API_KEYも設定されている場合、サーバーは起動時に失敗します
  • あなたのトークンが有効であることを確認するためにnpx @deque/axe-auth tokenをターミナルで実行してください。ゼロ以外のコードで終了した場合は、npx @deque/axe-auth loginを使って再認証してください。
  • axe サーバーの URL が正しいことを確認してください
  • セッションの途中でトークンが期限切れになる場合、起動時に単一のトークンをキャプチャしている構成になります。@deque/axe-auth runを介してサーバーを起動してください。これにより、実行中のサーバーのトークンが更新されます — 長時間のセッションを維持するを参照してください。
  • axe-auth runがトークン更新がサーバーに到達できなかったと報告した場合、更新ポートが一致していません：AXE_TOKEN_REFRESH_PORTとDocker-p 127.0.0.1:<port>:<port>が同じポートを指定していること、およびコンテナがAXE_TOKEN_REFRESH_HOST=0.0.0.0を設定していることを確認してください。トークン更新変数を参照してください。
  • 完全な OAuth トラブルシューティング手順については認証を確認してください

ヘルプを得る

このトラブルシューティングセクションでカバーされていない問題が発生した場合:

  1. 詳細なエラーメッセージを確認するために MCP クライアントの開発者コンソール/ログを確認してください（例：VS Code 開発者コンソール、Cursor の開発者ツール、または Claude Code の--debug出力）。
  2. サーバーログを確認してください — Dockerコンテナのログ、またはnpm配布を使用している場合はMCPクライアントのログ
  3. 次の情報を含めてhelpdesk@deque.comでサポートチームにご連絡ください：
    • MCP クライアントとそのバージョン
    • ご利用のDockerバージョン（Docker配布）またはNode.jsバージョン（npm配布）
    • エラーの完全なメッセージ
    • 問題を再現するための手順

Is this page helpful?

Help us improve this page

Still need help?