Fehlerbehebung

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

Diese Seite behandelt häufige Probleme in Bezug auf beide Docker- als auch npm-Distributionen. Probleme, die nur auf eine Distribution zutreffen, 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)
  • Überprüfen Sie, ob Ihre Anmeldedaten korrekt sind: entweder Ihr AXE_API_KEY oder Ihr 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 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

Der Scan des lokalen Entwicklungsservers schlägt mit ERR_CONNECTION_REFUSEDfehl

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

Beispiel für einen Fehler:

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

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

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

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

Erweiterte Regeln wurden nicht ausgeführt

Überprüfen Sie zuerst den advancedRules-Block in der analyze-Antwort — sein source-Feld benennt den Grund:

source Was zu tun ist
org_default Es ist nichts falsch. Wenn value disabled ist, hat Ihr Administrator das als Standard für die Organisation in axe-Konfiguration festgelegt.
org_policy_locked Ihr Administrator hat die Einstellung gesperrt. Überschreibungen werden absichtlich ignoriert — bitten Sie ihn, „Benutzern erlauben, Änderungen vorzunehmen“ zu überprüfen.
unavailable Erweiterte Regeln sind für diesen Server nicht verfügbar oder die axe-Konfiguration hat keinen verwendbaren Wert für sie zurückgegeben.

Andere Dinge, die überprüft werden sollten:

  • Der advancedRules-Parameter wird von Ihrem Agenten nicht angeboten. Das analyze-Tool bietet es nur an, wenn Erweiterte Regeln für Ihre Organisation verfügbar sind. Starten Sie die MCP-Serververbindung neu, damit Ihr Client die Werkzeugliste nach Ihren Zugriffsänderungen neu einliest.
  • AXE_ADVANCED_RULES hatte keine Wirkung. Bestätigen Sie, dass der Server tatsächlich mit ihm gestartet wurde (ein Tippfehler verhindert den Start — siehe AXE_ADVANCED_RULES), und dass ein Argument pro Aufruf advancedRules nicht den Vorrang hat.
  • Erweiterte Ergebnisse fehlen in data. Erweiterte Ergebnisse, die zu "muss überprüft werden" abgestuft wurden, werden herausgefiltert, es sei denn, Standard Muss überprüft werden ist in axe-Konfiguration aktiviert. Überprüfen Sie das messages-Array der Antwort auf eine Mitteilung über eine Abstufung.
  • Scans laufen nach der Aktivierung der Erweiterten Regeln ab. Sie fügen ungefähr 15–20 Sekunden pro Scan hinzu. Erhöhen Sie BROWSER_TIMEOUT_MS.
  • Erweiterte Regeln wurden während der Sitzung gestoppt. Wenn Deque einen Scan ablehnt, weil Erweiterte Regeln für Ihre Organisation nicht verfügbar sind, stoppt der Server den Versuch für den Rest dieses Vorgangs. Starten Sie ihn nach einer Abo-Änderung neu.

Siehe Erweiterte Regeln für die vollständige Referenz.

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 genügend Speicher verfügt, indem Sie einen docker system prune ausführen

Chromium-Installation (npm)

Dieser Abschnitt gilt für die npm-Distribution. Die Docker-Distribution bündelt 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 Barrierefreiheitsüberprüfungen durch, indem er einen echten Browser über Playwright steuert. Bei der npm-Distribution muss dieser Browser — Chromium — auf Ihrem Host installiert sein. Wenn es fehlt oder wenn die installierte Version nicht der Chromium-Version entspricht, die Playwright in der gelieferten Serverversion erwartet, schlägt der Server beim Starten (oder beim ersten Scan) mit einem Fehler fehl, der darauf hinweist, dass Chromium nicht gestartet werden konnte.

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

Standardlösung

tip

Die Fehlermeldung ist die zuverlässigste Quelle. Sie benennt den genauen angehefteten Befehl für den Server, den Sie tatsächlich ausführen — führen Sie diesen wörtlich aus. Die unten stehenden Befehle leiten den gleichen Pin von der letzten veröffentlichten Version ab, was korrekt ist, sofern Sie nicht an eine ältere axe-mcp-server angeheftet sind.

Installieren Sie die Chromium-Version, die zur Playwright-Version passt, mit der der axe MCP-Server geliefert wird. Playwright muss angeheftet sein, sodass ein nacktes npx playwright nicht auf eine neuere Version mit einer Chromium-Version auflöst, die der Server nicht unterstützt:

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

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

Wenn Sie einen älteren angehefteten Server ausführen, ersetzen Sie seine Version — npm view axe-mcp-server@<version> dependencies.playwright — oder nehmen Sie den Pin aus der Fehlermeldung. Zum Zeitpunkt des Schreibens liefert die Serverversion 1.4.0 Playwright 1.61.1.

Unter Windows cmd.exe, das keine $(...)-Ersatzfunktion hat, führen Sie npm view axe-mcp-server dependencies.playwright separat aus und fügen die Version ein. PowerShell, Git Bash und WSL verarbeiten die Befehle wie geschrieben.

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

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

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

Verwenden Sie einen Browser, den Sie bereits haben

Wenn Sie bereits über eine kompatible Chrome-/Chromium-Binärdatei auf Ihrem Host verfügen, 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 Anforderungen – beachten Sie, dass das gebrandete Google Chrome stable 137+ nicht unterstützt wird und der Wert eine ausführbare Binärdatei und kein .app-Bundle sein muss.

Warum Chromium nicht gebündelt wird

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

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

Das Upgrade von axe-mcp-server kann eine neuere Playwright-Version mit sich bringen, die eine neuere Chromium-Revision fixiert, die anders ist als die aktuell installierte. Wenn das passiert, könnten Sie denselben Startfehler erneut sehen nach einem Upgrade. Die Lösung ist dieselbe – führen Sie die Installation mit der Playwright-Version aus, die der aktualisierte Server liefert, damit Chromium übereinstimmt:

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

Da der Pin abgeleitet und nicht fest codiert ist, bleibt derselbe Befehl über Upgrades hinweg korrekt. Führen Sie ihn erneut aus, sobald Sie axe-mcp-server aktualisieren und der Server bei der Startmeldung ein Chromium-Mismatch 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
  • Stellen Sie sicher, 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 vor Ort gehostete axe-Instanz verwendet, muss AXE_SERVER_URL auf die Basis-URL Ihrer Instanz gesetzt sein. Details siehe Konfigurationsreferenz.

OAuth

  • Stellen Sie sicher, 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 Nicht-Null-Code 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 abläuft, erfasst Ihre Konfiguration ein einzelnes Token beim Start. Starten Sie den Server stattdessen über @deque/axe-auth run, das das Token des laufenden Servers automatisch aktualisiert — siehe Eine lange Sitzung am Leben halten
  • Wenn axe-auth run meldet, dass die Token-Aktualisierung den Server nicht erreichen konnte, stimmt der Aktualisierungs-Port nicht überein: Überprüfen Sie, ob AXE_TOKEN_REFRESH_PORT und Docker--p 127.0.0.1:<port>:<port> denselben Port benennen und der Container AXE_TOKEN_REFRESH_HOST=0.0.0.0 setzt. Siehe Token-Aktualisierungsvariablen
  • Siehe Authentifizierung für vollständige OAuth-Fehlerbehebungsschritte

Hilfe bekommen

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

  1. Überprüfen Sie die Entwicklerkonsole/Logs Ihres MCP-Clients auf detaillierte Fehlermeldungen (z.B. die VS Code Developer Console, Cursor's Developer Tools oder Claude Code's --debug Ausgabe)
  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:
    • Ihr MCP-Client und dessen Version
    • Ihre Docker-Version (Docker-Distribution) oder Node.js-Version (npm-Distribution)
    • Vollständige Fehlermeldungen
    • Schritte zur Reproduktion des Problems

Is this page helpful?

Help us improve this page

Still need help?