Probleemoplossing

Deze pagina behandelt veelvoorkomende problemen in beide 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 inloggegevens correct zijn: ofwel uw AXE_API_KEY ofwel uw AXE_ACCESS_TOKEN, maar niet beide (de server start niet op 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 ontwikkelingsserverscan mislukt met ERR_CONNECTION_REFUSED

Dit geldt voor de Docker-distributie — met de npm-distributie draait de server direct op uw host en kan localhost-diensten normaal bereiken.

Als het analyze-hulpmiddel faalt met een net::ERR_CONNECTION_REFUSED-fout tijdens het proberen een lokaal draaiende ontwikkelingsserver te scannen, komt dit waarschijnlijk omdat de axe MCP-server binnen een Docker-container draait en geen toegang heeft tot diensten die alleen zijn gebonden 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, waardoor hij 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 uit te voeren

Chromium-installatie (npm)

Dit gedeelte is van toepassing op de npm-distributie. De Docker-distributie bundelt zijn eigen browser, zodat Docker-gebruikers Chromium niet hoeven te installeren en niet worden beïnvloed 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. Met de npm-distributie moet die browser — Chromium — op uw host zijn geïnstalleerd. Als hij ontbreekt, of als de geïnstalleerde versie niet overeenkomt met de Chromium-revisie die de Playwright-versie van de server verwacht, start de server niet op (of faalt hij bij de eerste scan) met een foutmelding die aangeeft 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 levert — momenteel 1.60.0. Pin Playwright vast aan die versie zodat een kale npx playwright niet naar een nieuwere release verwijst 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 u al een compatibele Chrome/Chromium-binaire heeft op uw host, kunt u de installatie van Playwright helemaal omzeilen door de AXE_CHROME_PATH-omgevingsvariabele in te stellen op die binaire. Dit is vaak de snelste oplossing wanneer de Playwright-download wordt geblokkeerd (beperkt netwerk, proxy) of wanneer het installeren van systeemafhankelijkheden geen optie is. Zie AXE_CHROME_PATH voor vereisten — let op dat de gebrande Google Chrome stabiele 137+ niet wordt ondersteund, en de waarde moet een uitvoerbare binaire zijn in plaats van een .app-bundel.

Waarom Chromium niet wordt meegeleverd

Playwright koppelt een specifieke Chromium-revisie aan elke Playwright-versie, en die revisie verandert in de loop van de tijd. Het bundelen van een browserbinaire in het npm-pakket zou de grootte ervan aanzienlijk vergroten, het pakket aan één platform-binaire koppelen en het zou verouderd raken zodra Playwright zijn gepinde revisie bijwerkt. Door Chromium via Playwright te installeren, wordt gegarandeerd dat u precies de revisie krijgt die uw geïnstalleerde versie verwacht voor uw platform. (De Docker-distributie kan een browser bundelen omdat de image is gebouwd voor een enkele, bekende omgeving.)

Opnieuw uitvoeren na een upgrade van axe-mcp-server

Een upgrade van axe-mcp-server kan een nieuwere Playwright-versie met zich meebrengen, die een nieuwere Chromium-revisie kan pinnen dan de momenteel geïnstalleerde. Wanneer dat gebeurt, kunt u dezelfde startfout opnieuw zien na een upgrade. De oplossing is hetzelfde — voer de installatie opnieuw uit met de Playwright-versie die de geüpgradede server levert zodat Chromium overeenkomt:

npx playwright@1.60.0 install chromium

Als vuistregel voert u dit commando opnieuw uit — met de Playwright-versie die de huidige release levert — elke keer dat u axe-mcp-server upgrade 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 niet opstarten
• Bevestig dat uw axe-server-URL correct is — als uw organisatie een regionaal, privé cloud- of on-premises axe-instance gebruikt, moet AXE_SERVER_URL worden ingesteld op de basis-URL van uw instance. Zie Configuratiereferentie voor details.

OAuth

• Bevestig dat alleen AXE_ACCESS_TOKEN is ingesteld — als AXE_API_KEY ook is ingesteld, zal de server niet opstarten
• Voer npx @deque/axe-auth token uit in uw terminal om te bevestigen dat u een geldig token heeft; als het met een niet-nulcode afsluit, meld dan opnieuw aan met npx @deque/axe-auth login
• Controleer of je axe-server-URL correct is
• Als uw token tijdens de sessie is verlopen, start dan de MCP-serververbinding opnieuw in uw client (bijvoorbeeld door Claude Code opnieuw te starten, de server uit en aan te schakelen in de MCP-instellingen van Cursor, of direct op de "Herstart"-knop van VS Code's CodeLens boven de axe MCP-serververmelding in mcp.json te klikken) 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 ontwikkelaarsconsole/logs van uw MCP-client voor gedetailleerde foutmeldingen (bijvoorbeeld de VS Code Developer Console, de Developer Tools van Cursor, of Claude Code's --debug-uitvoer)
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 ondersteuningsteam op helpdesk@deque.com met:
   • Uw MCP-client en de versie ervan
   • Uw Docker-versie (Docker-distributie) of Node.js-versie (npm-distributie)
   • Volledige foutmeldingen
   • Stappen om het probleem te reproduceren