Probleemoplossing

Deze pagina behandelt veelvoorkomende problemen in zowel de Docker- als npm-distributies. Problemen die alleen op één distributie van toepassing zijn, worden dienovereenkomstig gelabeld.

Server start niet

• Zorg ervoor dat Docker draait (Docker-distributie), of dat Chromium is geïnstalleerd (npm-distributie — zie Chromium-installatie)
• Controleer of uw referenties correct zijn: ofwel uw AXE_API_KEY of uw AXE_ACCESS_TOKEN, maar niet beide (de server start niet als beide zijn ingesteld)
• Controleer of u toegang heeft tot de axe MCP Server (neem contact op met ondersteuning indien nodig)

Scantime-outs

• Verhoog BROWSER_TIMEOUT_MS voor complexe pagina's
• Zorg ervoor dat de doel-URL toegankelijk is via uw netwerk
• Controleer op netwerkconnectiviteitsproblemen

Lokale ontwikkelingsserver-scan mislukt met ERR_CONNECTION_REFUSED

Dit geldt voor de Docker-distributie — bij de npm-distributie draait de server direct op uw host en kan normaal toegang krijgen tot localhost diensten.

Als de analyze tool faalt met een net::ERR_CONNECTION_REFUSED fout bij het proberen te scannen van een lokaal draaiende ontwikkelingsserver, komt dit waarschijnlijk omdat de axe MCP Server binnen een Docker-container draait en geen toegang heeft tot diensten die alleen gebonden zijn aan localhost (d.w.z., 127.0.0.1) op uw hostmachine.

Foutvoorbeeld:

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

Oplossing: Start uw ontwikkelingsserver met de --host vlag ingesteld op 0.0.0.0 zodat deze luistert op alle netwerkinterfaces en vanuit de Docker-container bereikbaar is:

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

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

Docker-problemen

• Zorg ervoor dat de Docker-daemon draait
• Controleer Docker-permissies
• Controleer netwerkconnectiviteit voor Docker-afbeeldingdownloads
• Zorg ervoor dat Docker voldoende geheugen heeft door een docker system prune

Chromium-installatie (npm)

Deze sectie is van toepassing op de npm-distributie. De Docker-distributie bevat zijn eigen browser, dus Docker-gebruikers hoeven Chromium niet te installeren en zijn niet getroffen door de hier beschreven fouten.

Wat de fout betekent

De axe MCP Server voert toegankelijkheidsscans uit door een echte browser aan te sturen via Playwright. Bij de npm-distributie moet die browser — Chromium — op uw host worden geïnstalleerd. Als deze ontbreekt, of als de geïnstalleerde versie niet overeenkomt met de Chromium-revisie die door de doorvoer van de Playwright-versie wordt verwacht, start de server niet (of faalt bij de eerste scan) met een foutmelding dat Chromium niet kon worden gestart.

Dit wordt verwacht bij een nieuwe installatie en is eenvoudig te verhelpen.

Standaardoplossing

Installeer de Chromium-revisie die overeenkomt met de Playwright-versie die de axe MCP Server meegeleverd krijgt — momenteel 1.60.0. Pin Playwright vast op die versie zodat een kale npx playwright niet te maken krijgt met een nieuwere release met een Chromium-revisie die de server niet ondersteunt:

npx playwright@1.60.0 install chromium

Start dan de MCP-server (of je MCP-client) opnieuw en probeer het opnieuw.

Linux-nazorg

Op Linux is Chromium ook afhankelijk van een aantal systeembibliotheken die mogelijk niet aanwezig zijn. Als de browser na de standaardoplossing nog steeds niet start, installeer dan deze afhankelijkheden:

sudo npx playwright@1.60.0 install-deps chromium

Je kunt beide stappen ook in één opdracht combineren:

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

Gebruik een browser die je al hebt

Als je al een compatibele Chrome/Chromium-binary op je host hebt staan, kun je de installatie van Playwright volledig omzeilen door de AXE_CHROME_PATH omgevingsvariabele in te stellen op die binary. Dit is vaak de snelste oplossing wanneer het downloaden van Playwright wordt geblokkeerd (beperkt netwerk, proxy) of wanneer het installeren van systeemafhankelijkheden geen optie is. Zie AXE_CHROME_PATH voor vereisten — merk op dat de merkgebonden stabiele versie van Google Chrome 137+ niet wordt ondersteund, en de waarde moet een uitvoerbare binary zijn in plaats van een .app bundel.

Waarom Chromium niet wordt meegeleverd

Playwright zet een specifieke Chromium-revisie vast aan elke Playwright-versie, en die revisie verandert in de loop der tijd. Het meeleveren van een browser-binary in het npm-pakket zou de grootte aanzienlijk vergroten, het pakket koppelen aan de binary van één platform en verouderen zodra Playwright zijn vastgezette revisie bijwerkt. Het installeren van Chromium via Playwright garandeert in plaats daarvan dat je precies de revisie krijgt die je geïnstalleerde versie verwacht, voor jouw platform. (De Docker-distributie kan een browser meeleveren omdat de image is gebouwd voor één, bekende omgeving.)

Opnieuw uitvoeren na een upgrade van axe-mcp-server

Upgraden van axe-mcp-server kan een nieuwere Playwright-versie met zich meebrengen, die een nieuwere Chromium-revisie kan vastzetten dan degene die momenteel geïnstalleerd is. Wanneer dat gebeurt, kun je dezelfde startfout opnieuw zien na een upgrade. De oplossing is dezelfde — voer de installatie opnieuw uit met de Playwright-versie die de geüpgrade server levert zodat Chromium overeenkomt:

npx playwright@1.60.0 install chromium

Als vuistregel, voer dit commando opnieuw uit — met de Playwright-versie die de huidige release levert — iedere keer als je axe-mcp-server upgradet en de server meldt een Chromium-mismatch bij het opstarten.

Authenticatiefouten

API-sleutel

• Controleer of je API-sleutel geldig is en niet is verlopen
• Zorg ervoor dat je axe Account Portal-abonnement MCP Server-toegang bevat
• Controleer of de API-sleutel is aangemaakt voor het product "axe MCP Server"
• Bevestig dat alleen AXE_API_KEY is ingesteld — als AXE_ACCESS_TOKEN ook is ingesteld, zal de server bij het opstarten falen
• Controleer of je axe-server-URL correct is — als je organisatie een regionale, private cloud- of on-premises axe-installatie gebruikt, AXE_SERVER_URL moet worden ingesteld op de basis-URL van je installatie. Zie Configuratiereferentie voor details.

OAuth

• Bevestig dat alleen AXE_ACCESS_TOKEN is ingesteld — als AXE_API_KEY ook is ingesteld, zal de server bij het opstarten falen
• Voer npx @deque/axe-auth token uit in je terminal om te bevestigen dat je een geldig token hebt; als het met een niet-nulcode afsluit, opnieuw authenticeren met npx @deque/axe-auth login
• Controleer of je axe-server-URL correct is
• Als je token halverwege de sessie is verlopen, herstart dan de MCP-serververbinding in je client (bijv. door Claude Code opnieuw te starten, de server aan en uit te schakelen in de MCP-instellingen van Cursor, of door direct boven de vermelding van axe MCP Server in mcp.jsonte klikken op de "Opnieuw starten" knop van CodeLens) om een nieuw token te verkrijgen
• Zie Authenticatie voor volledige OAuth-probleemoplossingsstappen

Hulp krijgen

Als je problemen ondervindt die niet worden behandeld in deze probleemoplossingssectie:

1. Controleer de VS Code Ontwikkelaarconsole voor gedetailleerde foutmeldingen
2. Controleer de serverlogs — de Docker-containerlogs, of de logs van uw MCP-client bij gebruik van de npm-distributie
3. Neem contact op met ons supportteam via helpdesk@deque.com met:
   • Uw VS Code-versie
   • Uw Docker-versie (Docker-distributie) of Node.js-versie (npm-distributie)
   • Volledige foutmeldingen
   • Stappen om het probleem te reproduceren