Troubleshooting

This page covers common issues across both the Docker and npm distributions. Issues that apply to only one distribution are labeled accordingly.

Server fails to start

• Ensure Docker is running (Docker distribution), or that Chromium is installed (npm distribution — see Chromium installation)
• Verify your credentials are correct: either your AXE_API_KEY or your AXE_ACCESS_TOKEN, but not both (the server fails at startup if both are set)
• Check that you have access to the axe MCP Server (contact support if needed)

Scan timeouts

• Increase BROWSER_TIMEOUT_MS for complex pages
• Ensure the target URL is accessible from your network
• Check for network connectivity issues

Local development server scan fails with ERR_CONNECTION_REFUSED

This applies to the Docker distribution — with the npm distribution the server runs directly on your host and can reach localhost services normally.

If the analyze tool fails with a net::ERR_CONNECTION_REFUSED error while trying to scan a locally running dev server, this is likely because axe MCP Server runs inside a Docker container and cannot reach services bound only to localhost (i.e., 127.0.0.1) on your host machine.

Error example:

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

Solution: 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

Docker issues

• Ensure the Docker daemon is running
• Check Docker permissions
• Verify network connectivity for Docker image downloads
• Ensure Docker has enough memory by running a docker system prune

Chromium installation (npm)

This section applies to the npm distribution. The Docker distribution bundles its own browser, so Docker users do not need to install Chromium and are not affected by the errors described here.

What the error means

The axe MCP Server runs accessibility scans by driving a real browser through Playwright. With the npm distribution, that browser — Chromium — must be installed on your host. If it is missing, or if the installed version does not match the Chromium revision the Playwright version the server ships expects, the server fails to start (or fails on the first scan) with an error indicating that Chromium could not be launched.

This is expected on a fresh install and is straightforward to fix.

Standard fix

Install the Chromium revision that matches the Playwright version the axe MCP Server ships — currently 1.60.0. Pin Playwright to that version so a bare npx playwright doesn't resolve to a newer release with a Chromium revision the server doesn't support:

npx playwright@1.60.0 install chromium

Then restart the MCP server (or your MCP client) and try again.

Linux follow-up

On Linux, Chromium also depends on a number of system libraries that may not be present. If the browser still fails to launch after the standard fix, install those dependencies:

sudo npx playwright@1.60.0 install-deps chromium

You can also combine both steps in a single command:

sudo npx playwright@1.60.0 install --with-deps chromium

Use a browser you already have

If you already have a compatible Chrome/Chromium binary on your host, you can sidestep the Playwright install entirely by setting the AXE_CHROME_PATH environment variable to that binary. This is often the quickest fix when the Playwright download is blocked (restricted network, proxy) or when installing system dependencies isn't an option. See AXE_CHROME_PATH for requirements — note that branded Google Chrome stable 137+ is not supported, and the value must be an executable binary rather than a .app bundle.

Why Chromium isn't bundled

Playwright pins a specific Chromium revision to each Playwright version, and that revision changes over time. Bundling a browser binary into the npm package would significantly inflate its size, tie the package to one platform's binary, and go stale as soon as Playwright updated its pinned revision. Installing Chromium through Playwright instead guarantees you get exactly the revision your installed version expects, for your platform. (The Docker distribution can bundle a browser because the image is built for a single, known environment.)

Re-running after an axe-mcp-server upgrade

Upgrading axe-mcp-server may bring in a newer Playwright version, which can pin a newer Chromium revision than the one currently installed. When that happens you may see the same launch error again after an upgrade. The fix is the same — re-run the install with the Playwright version the upgraded server ships so Chromium matches:

npx playwright@1.60.0 install chromium

As a rule of thumb, re-run this command — using the Playwright version the current release ships — any time you upgrade axe-mcp-server and the server reports a Chromium mismatch on startup.

Authentication errors

API key

• Verify your API key is valid and hasn't expired
• Ensure your axe Account Portal subscription includes MCP Server access
• Check that the API key was created for "axe MCP Server" product
• Confirm only AXE_API_KEY is set — if AXE_ACCESS_TOKEN is also set, the server will fail at startup
• Confirm your axe server URL is correct — if your organization uses a regional, private cloud, or on-premises axe instance, AXE_SERVER_URL must be set to your instance's base URL. See Configuration Reference for details.

OAuth

• Confirm only AXE_ACCESS_TOKEN is set — if AXE_API_KEY is also set, the server will fail at startup
• Run npx @deque/axe-auth token in your terminal to confirm you have a valid token; if it exits with a non-zero code, re-authenticate with npx @deque/axe-auth login
• Confirm your axe server URL is correct
• If your token has expired mid-session, restart the MCP server connection in your client (e.g., restarting Claude Code, toggling the server off and on in Cursor's MCP settings, or clicking VS Code's CodeLens "Restart" button directly above the axe MCP Server entry in mcp.json) to obtain a fresh token
• See Authentication for full OAuth troubleshooting steps

Getting Help

If you encounter issues not covered in this troubleshooting section:

1. Check the VS Code Developer Console for detailed error messages
2. Review the server logs — the Docker container logs, or your MCP client's logs when using the npm distribution
3. Contact our support team at helpdesk@deque.com with:
   • Your VS Code version
   • Your Docker version (Docker distribution) or Node.js version (npm distribution)
   • Complete error messages
   • Steps to reproduce the issue