Fehlerbehebung

Diese Seite behandelt häufige Probleme sowohl in den Docker- als auch npm-Distributionen. Probleme, die nur eine Distribution betreffen, sind entsprechend gekennzeichnet.

Server startet nicht

• Stellen Sie sicher, dass Docker läuft (Docker-Distribution) oder dass Chromium installiert ist (npm-Distribution — siehe Chromium-Installation)
• Stellen Sie sicher, dass Ihre Zugangsdaten korrekt sind: entweder Ihre AXE_API_KEY oder Ihre AXE_ACCESS_TOKEN, aber nicht beide (der Server schlägt beim Start fehl, wenn beide gesetzt sind)
• Prüfen Sie, ob Sie Zugriff auf den axe MCP-Server haben (kontaktieren Sie den Support, falls erforderlich)

Scan-Zeitüberschreitungen

• Erhöhen Sie die BROWSER_TIMEOUT_MS für komplexe Seiten
• Stellen Sie sicher, dass die Ziel-URL von Ihrem Netzwerk aus zugänglich ist
• Prüfen Sie auf Netzwerkverbindungsprobleme

Scan des lokalen Entwicklungsservers schlägt fehl mit ERR_CONNECTION_REFUSED

Dies gilt für die Docker-Distribution — bei der npm-Distribution läuft der Server direkt auf Ihrem Host und kann localhost Dienste normal erreichen.

Wenn das analyze Werkzeug mit einem net::ERR_CONNECTION_REFUSED Fehler beim Versuch, einen lokal laufenden Entwicklungsserver zu scannen, fehlschlägt, liegt das wahrscheinlich daran, dass der axe MCP-Server in einem Docker-Container läuft und Dienste, die nur an localhost (d.h. 127.0.0.1) auf Ihrem Host gebunden sind, nicht erreichen kann.

Beispiel für einen Fehler:

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

Lösung: Starten Sie Ihren Entwicklungsserver mit dem --host Flag auf 0.0.0.0 gesetzt, sodass er auf allen Netzwerkschnittstellen hört und vom Docker-Container aus erreichbar ist:

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

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

Docker-Probleme

• Stellen Sie sicher, dass der Docker-Daemon läuft
• Überprüfen Sie die Docker-Berechtigungen
• Überprüfen Sie die Netzwerkkonnektivität für Docker-Image-Downloads
• Stellen Sie sicher, dass Docker über ausreichend Arbeitsspeicher verfügt, indem Sie ein docker system prune

Chromium-Installation (npm)

Dieser Abschnitt gilt für die npm-Distribution. Die Docker-Distribution enthält ihren eigenen Browser, sodass Docker-Benutzer Chromium nicht installieren müssen und von den hier beschriebenen Fehlern nicht betroffen sind.

Was der Fehler bedeutet

Der axe MCP-Server führt Barrierefreiheitsscans durch, indem er einen echten Browser über Playwrightsteuert. Bei der npm-Distribution muss dieser Browser — Chromium — auf Ihrem Host installiert sein. Wenn er fehlt oder die installierte Version nicht mit der Chromium-Version übereinstimmt, die die Playwright-Version des Servers erwartet, schlägt der Serverstart fehl (oder der erste Scan), mit einem Fehler, der darauf hinweist, dass Chromium nicht gestartet werden konnte.

Dies ist bei einer Neuinstallation zu erwarten und leicht zu beheben.

Standardlösung

Installieren Sie die Chromium-Version, die der Playwright-Version entspricht, die der axe MCP-Server liefert — aktuell 1.60.0. Fixieren Sie Playwright auf diese Version, damit ein einfaches npx playwright nicht auf eine neuere Version mit einer Chromium-Revision aufgelöst wird, die der Server nicht unterstützt:

npx playwright@1.60.0 install chromium

Starten Sie dann den MCP-Server (oder Ihren MCP-Client) neu und versuchen Sie es erneut.

Nachverfolgung für Linux

Unter Linux hängt Chromium auch von mehreren Systembibliotheken ab, die eventuell nicht vorhanden sind. Falls der Browser nach der Standardlösung immer noch nicht startet, installieren Sie diese Abhängigkeiten:

sudo npx playwright@1.60.0 install-deps chromium

Sie können auch beide Schritte in einem einzigen Befehl kombinieren:

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

Verwenden Sie einen Browser, den Sie bereits haben

Wenn Sie bereits eine kompatible Chrome-/Chromium-Binärdatei auf Ihrem Host haben, können Sie die Playwright-Installation vollständig umgehen, indem Sie die AXE_CHROME_PATH Umgebungsvariable auf diese Binärdatei setzen. Dies ist oft die schnellste Lösung, wenn der Playwright-Download blockiert ist (eingeschränktes Netzwerk, Proxy) oder wenn die Installation von Systemabhängigkeiten keine Option ist. Siehe AXE_CHROME_PATH für die Anforderungen — beachten Sie, dass das gebrandete Google Chrome stable 137+ nicht unterstützt wird, und der Wert muss eine ausführbare Binärdatei sein, anstatt eines .app Pakets.

Warum Chromium nicht gebündelt wird

Playwright fixiert eine spezifische Chromium-Revision auf jede Playwright-Version, und diese Revision ändert sich im Laufe der Zeit. Ein Browser-Binärdatei in das npm-Paket zu bündeln, würde dessen Größe erheblich vergrößern, das Paket an das Binary einer Plattform binden und veralten, sobald Playwright seine fixierte Version aktualisiert. Die Installation von Chromium über Playwright garantiert stattdessen, dass Sie genau die Revision erhalten, die Ihre installierte Version für Ihre Plattform erwartet. (Die Docker-Distribution kann einen Browser bündeln, da das Image für eine einzige, bekannte Umgebung erstellt wird.)

Erneutes Ausführen nach einem Upgrade des axe-mcp-servers

Ein Upgrade von axe-mcp-server kann eine neuere Playwright-Version einbringen, die eine neuere Chromium-Revision als die derzeit installierte fixiert. Wenn dies passiert, können Sie denselben Startfehler nach einem Upgrade wieder sehen. Die Lösung ist die gleiche — führen Sie die Installation mit der Playwright-Version durch, die der aktualisierte Server liefert, sodass Chromium übereinstimmt:

npx playwright@1.60.0 install chromium

Als Faustregel gilt: Führen Sie diesen Befehl erneut aus — verwenden Sie die Playwright-Version, die die aktuelle Version liefert — jedes Mal, wenn Sie axe-mcp-server aktualisieren und der Server bei Start eine Chromium-Unstimmigkeit meldet.

Authentifizierungsfehler

API-Schlüssel

• Stellen Sie sicher, dass Ihr API-Schlüssel gültig ist und nicht abgelaufen ist
• Stellen Sie sicher, dass Ihr axe Account Portal-Abonnement den Zugriff auf den MCP-Server enthält
• Überprüfen Sie, dass der API-Schlüssel für das Produkt „axe MCP Server“ erstellt wurde
• Bestätigen Sie, dass nur AXE_API_KEY gesetzt ist — wenn AXE_ACCESS_TOKEN ebenfalls gesetzt ist, schlägt der Server beim Start fehl
• Stellen Sie sicher, dass Ihre axe-Server-URL korrekt ist — wenn Ihre Organisation eine regionale, private Cloud oder eine lokale axe-Instanz verwendet, AXE_SERVER_URL muss auf die Basis-URL Ihrer Instanz gesetzt sein. Siehe Konfigurationsreferenz für Details.

OAuth

• Bestätigen Sie, dass nur AXE_ACCESS_TOKEN gesetzt ist — wenn AXE_API_KEY ebenfalls gesetzt ist, schlägt der Server beim Start fehl
• Führen Sie npx @deque/axe-auth token in Ihrem Terminal aus, um zu bestätigen, dass Sie ein gültiges Token haben; wenn es mit einem anderen Wert als 0 endet, authentifizieren Sie sich erneut mit npx @deque/axe-auth login
• Stellen Sie sicher, dass Ihre axe-Server-URL korrekt ist
• Wenn Ihr Token während der Sitzung abgelaufen ist, starten Sie die Verbindung zum MCP-Server in Ihrem Client neu (z. B. durch Neustart von Claude Code, Umschalten des Servers in den MCP-Einstellungen von Cursor oder direktes Klicken auf den "Restart"-Button oberhalb des Eintrags "axe MCP Server" in mcp.json), um ein neues Token zu erhalten
• Siehe Authentifizierung für vollständige Fehlerbehebungsschritte für OAuth

Hilfe bekommen

Wenn Sie auf Probleme stoßen, die in diesem Fehlerbehebungsabschnitt nicht behandelt werden:

1. Überprüfen Sie die Entwicklerkonsole von VS Code auf detaillierte Fehlermeldungen
2. Überprüfen Sie die Serverprotokolle – die Docker-Container-Protokolle oder die Protokolle Ihres MCP-Clients bei Verwendung der npm-Distribution
3. Kontaktieren Sie unser Support-Team unter helpdesk@deque.com mit:
   • Ihre VS Code-Version
   • Ihre Docker-Version (Docker-Distribution) oder Node.js-Version (npm-Distribution)
   • Vollständige Fehlermeldungen
   • Schritte zur Reproduktion des Problems