Probleemoplossing

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

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

Geavanceerde regels zijn niet uitgevoerd

Controleer eerst het advancedRules blok in de analyze respons — het source veld noemt de reden:

source Wat te doen
org_default Er is niets mis. Als value disabled is, heeft uw beheerder dat als de standaard voor de organisatie ingesteld in axe-configuratie.
org_policy_locked Uw beheerder heeft de instelling vergrendeld. Overrides worden opzettelijk genegeerd — vraag hen om „Gebruikers toestaan te wijzigen“ te controleren.
unavailable Geavanceerde regels zijn niet beschikbaar voor deze server, of axe-configuratie heeft geen bruikbare waarde voor hen geretourneerd.

Andere dingen om te controleren:

  • De advancedRules parameter wordt niet aangeboden door uw agent. Het analyze hulpmiddel biedt het alleen aan wanneer geavanceerde regels beschikbaar zijn voor uw organisatie. Herstart de MCP-serververbinding zodat uw client de hulpmiddelenlijst opnieuw leest nadat uw toegang is gewijzigd.
  • AXE_ADVANCED_RULES had geen effect. Bevestig dat de server daadwerkelijk daarmee is gestart (een typfout leidt tot een mislukte start — zie AXE_ADVANCED_RULES), en dat een specifieke advancedRules argument dat niet domineert.
  • Geavanceerde bevindingen ontbreken in data. Geavanceerde bevindingen die zijn gedegradeerd tot herziening zijn gefilterd tenzij Standaard vereist herziening is ingeschakeld in axe-configuratie. Controleer het messages array van de respons op een degradatiebericht.
  • Scans verlopen na het inschakelen van geavanceerde regels. Ze voegen ongeveer 15–20 seconden per scan toe. Verhoog BROWSER_TIMEOUT_MS.
  • Geavanceerde regels stopten halverwege de sessie. Als Deque een scan afwijst omdat geavanceerde regels niet beschikbaar zijn voor uw organisatie, stopt de server met pogingen gedurende de rest van dat proces. Herstart het na een abonnementswijziging.

Zie Geavanceerde regels voor de volledige referentie.

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

tip

Het foutbericht is de meest betrouwbare bron. Het noemt het exacte vastgezette commando voor de server die u daadwerkelijk uitvoert — voer dat letterlijk uit. De commando's hieronder halen dezelfde pin uit de laatst gepubliceerde release, wat correct is tenzij u vastgepind bent aan een oudere axe-mcp-server.

Installeer de Chromium-revisie die overeenkomt met de Playwright-versie die de axe MCP-server levert. Playwright moet vastgepind zijn, dus een kale npx playwright leidt niet tot een nieuwere release met een Chromium-revisie die de server niet ondersteunt:

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

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

Als u een vastgepinde oudere server uitvoert, vervang dan zijn versie — npm view axe-mcp-server@<version> dependencies.playwright — of haal de pin uit het foutbericht. Op het moment van schrijven levert serverversie 1.4.0 Playwright 1.61.1.

Op Windows cmd.exe, dat geen $(...) vervanging heeft, voer npm view axe-mcp-server dependencies.playwright afzonderlijk uit en plak de versie erin. PowerShell, Git Bash en WSL verwerken de commando's zoals geschreven.

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

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

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

Omdat de pin is afgeleid in plaats van hardgecodeerd, blijft hetzelfde commando correct bij upgrades. Voer het opnieuw uit telkens wanneer u axe-mcp-server upgradet en de server een Chromium-mismatch rapporteert 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 halverwege de sessie verloopt, legt uw configuratie een enkele token vast bij het opstarten. Start de server in plaats daarvan via @deque/axe-auth run, wat het token van de draaiende server voor u ververs — zie Een lange sessie in leven houden
  • Als axe-auth run rapporteert dat tokenvernieuwing de server niet kon bereiken, komt de vernieuwingspoort niet overeen: controleer of AXE_TOKEN_REFRESH_PORT en de Docker -p 127.0.0.1:<port>:<port> dezelfde poort noemen, en dat de container AXE_TOKEN_REFRESH_HOST=0.0.0.0 instelt. Zie Token vernieuwingsvariabelen
  • 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

Is this page helpful?

Help us improve this page

Still need help?