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)
• Read the startup error: it names the setting that's wrong, such as an invalid proxy URL or an AXE_CHROME_PATH that can't launch, and says why
• On a network that only allows outbound traffic through a proxy, see Corporate proxy

Scan timeouts

• Ensure the target URL is accessible from your network
• Check for network connectivity issues
• Raise the timeout for the phase that actually timed out. Each is an independent budget, so raising the wrong one changes nothing. Match the error text you got, then see Configuration Options for defaults:

An Intelligent Guided Test that times out does not fail the surrounding analyze call: the axe results still come back, with the failure reported under that test's own status.

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

Untrusted certificates

If a scan fails with net::ERR_CERT_AUTHORITY_INVALID, the scan browser doesn't trust the certificate authority (CA) that signed the page's certificate. This is common for intranet sites signed by an internal CA, and on networks with a proxy that inspects TLS traffic. Your agent relays the fix for your platform:

• Docker and npm on Linux — set NODE_EXTRA_CA_CERTS to the path of the CA certificate (PEM format), then restart the server. Under Docker, also mount the file into the container. On npm, install certutil first (libnss3-tools on Debian/Ubuntu, nss-tools on RHEL/Fedora).
• npm on macOS — add the CA to your login keychain, trusted for SSL only.
• npm on Windows — add the CA to your Current User Trusted Root store, trusted for SSL only.

On macOS and Windows, the browser picks up the change on the next scan, with no restart needed.

If you've already set NODE_EXTRA_CA_CERTS and scans still fail, check the server's startup log for a warning about the certificate, such as certutil not being installed, or the file containing more than one certificate when only the first one is added to the browser. If the file doesn't exist or can't be read, the server doesn't start at all, and the startup error says so.

This applies only to an untrusted CA. Expired, revoked, or wrong-hostname certificates are problems with the site's certificate itself, and adding a CA doesn't fix them.

If you can't add the CA, NODE_TLS_REJECT_UNAUTHORIZED turns off certificate checks entirely. Use it only for local testing, and try NODE_EXTRA_CA_CERTS first.

Corporate proxy

If your network only allows outbound traffic through a proxy, the server can't reach the axe server, so it fails at startup or when validating your credentials. Set HTTPS_PROXY to the proxy's full URL. See Proxy variables.

If you use OAuth 2.0, also set NODE_USE_ENV_PROXY=1 so the @deque/axe-auth CLI signs you in and refreshes tokens through the proxy. This requires Node.js 22.21 or later. See Proxy variables.

• Intranet pages don't load in scans: the scan browser uses the proxy too. Add those hosts to NO_PROXY.
• The server logs a warning about proxy credentials: the scan browser can't use a proxy that needs a username and password. Ask your network team for a proxy endpoint that doesn't require them, or one that allows the scan browser's traffic through.
• Requests fail with certificate errors once the proxy is set: the proxy is inspecting TLS traffic. Also set NODE_EXTRA_CA_CERTS to the proxy's CA certificate.

Advanced Rules didn't run

Check the advancedRules block in the analyze response first — its source field names the reason:

Other things to check:

• The advancedRules parameter isn't offered by your agent. The analyze tool only offers it when Advanced Rules are available to your organization. Restart the MCP server connection so your client re-reads the tool list after your access changes.
• AXE_ADVANCED_RULES had no effect. Confirm the server actually started with it (a typo fails startup — see AXE_ADVANCED_RULES), and that a per-call advancedRules argument isn't taking precedence.
• Advanced findings are missing from data. Advanced findings that degraded to needs-review are filtered out unless Default Needs Review is enabled in Axe Configuration. Check the response's messages array for a degradation message.
• Scans time out after enabling Advanced Rules. They add roughly 15–20 seconds per scan. Raise BROWSER_TIMEOUT_MS.
• Advanced Rules stopped running mid-session. If Deque rejects a scan because Advanced Rules aren't available to your organization, the server stops attempting them for the rest of that process. Restart it after a subscription change.

See Advanced Rules for the full reference.

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 matching the Playwright version the Axe MCP Server ships. Playwright must be pinned, so a bare npx playwright doesn't resolve to a newer release with a Chromium revision the server doesn't support:

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

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

If you run a pinned older server, substitute its version — npm view axe-mcp-server@<version> dependencies.playwright — or take the pin from the error message. At the time of writing, server version 1.4.0 ships Playwright 1.61.1.

On Windows cmd.exe, which has no $(...) substitution, run npm view axe-mcp-server dependencies.playwright separately and paste the version in. PowerShell, Git Bash, and WSL handle the commands as written.

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@$(npm view axe-mcp-server dependencies.playwright) install-deps chromium

You can also combine both steps in a single command:

sudo npx playwright@$(npm view axe-mcp-server dependencies.playwright) 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@$(npm view axe-mcp-server dependencies.playwright) install chromium

Because the pin is derived rather than hard-coded, the same command stays correct across upgrades. Re-run it 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 expires mid-session, your configuration is capturing a single token at startup. Launch the server through @deque/axe-auth run instead, which refreshes the running server's token for you — see Keeping a long session alive
• If axe-auth run reports that token refresh could not reach the server, the refresh port does not line up: check that AXE_TOKEN_REFRESH_PORT and the Docker -p 127.0.0.1:<port>:<port> publish name the same port, and that the container sets AXE_TOKEN_REFRESH_HOST=0.0.0.0. See Token refresh variables
• See Authentication for full OAuth troubleshooting steps

Getting Help

If you encounter issues not covered in this troubleshooting section:

1. Check your MCP client's developer console/logs for detailed error messages (e.g., the VS Code Developer Console, Cursor's Developer Tools, or Claude Code's --debug output)
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 MCP client and its version
   • Your Docker version (Docker distribution) or Node.js version (npm distribution)
   • Complete error messages
   • Steps to reproduce the issue