Dépannage

Cette page couvre les problèmes courants des deux Docker et npm. Les problèmes qui s'appliquent uniquement à une distribution sont étiquetés en conséquence.

Le serveur ne démarre pas

• Assurez-vous que Docker fonctionne (distribution Docker), ou que Chromium est installé (distribution npm — voir installation de Chromium)
• Vérifiez que vos identifiants sont corrects : soit votre AXE_API_KEY, soit votre AXE_ACCESS_TOKEN, mais pas les deux (le serveur échoue au démarrage si les deux sont définis)
• Vérifiez que vous avez accès au serveur axe MCP (contactez le support si nécessaire)

Les analyses prennent trop de temps

• Augmentez BROWSER_TIMEOUT_MS pour les pages complexes
• Assurez-vous que l'URL cible est accessible depuis votre réseau
• Vérifiez les problèmes de connectivité réseau

Le serveur de développement local échoue avec ERR_CONNECTION_REFUSED

Cela s'applique à distribution Docker — avec la distribution npm, le serveur fonctionne directement sur votre hôte et peut atteindre des services localhost normalement.

Si l'outil analyze échoue avec une erreur net::ERR_CONNECTION_REFUSED lors de la tentative d'analyse d'un serveur de développement local, c'est probablement parce que le serveur axe MCP fonctionne à l'intérieur d'un conteneur Docker et ne peut pas atteindre les services liés uniquement à localhost (c'est-à-dire, 127.0.0.1) sur votre machine hôte.

Exemple d'erreur :

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

Solution : Démarrez votre serveur de développement avec le drapeau --host réglé sur 0.0.0.0 pour qu'il écoute toutes les interfaces réseau, le rendant accessible depuis le conteneur Docker :

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

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

Problèmes Docker

• Assurez-vous que le démon Docker est en cours d'exécution
• Vérifiez les autorisations Docker
• Vérifiez la connectivité réseau pour les téléchargements d'images Docker
• Assurez-vous que Docker dispose de suffisamment de mémoire en exécutant une docker system prune

Installation de Chromium (npm)

Cette section s'applique à distribution npm. La distribution Docker inclut son propre navigateur, donc les utilisateurs de Docker n'ont pas besoin d'installer Chromium et ne sont pas affectés par les erreurs décrites ici.

Que signifie l'erreur

Le serveur axe MCP effectue des analyses d'accessibilité en utilisant un navigateur réel via Playwright. Avec la distribution npm, ce navigateur — Chromium — doit être installé sur votre hôte. S'il manque, ou si la version installée ne correspond pas à la révision de Chromium que la version de Playwright attend, le serveur échoue à démarrer (ou échoue à la première analyse) avec une erreur indiquant que Chromium n'a pas pu être lancé.

C'est attendu lors d'une nouvelle installation et il est simple de résoudre ce problème.

Correction standard

Installez la révision de Chromium qui correspond à la version de Playwright que le serveur axe MCP fournit — actuellement 1.60.0. Verrouillez Playwright à cette version pour qu'un simple npx playwright ne se résolve pas en une nouvelle version avec une révision de Chromium que le serveur ne supporte pas :

npx playwright@1.60.0 install chromium

Redémarrez ensuite le serveur MCP (ou votre client MCP) et réessayez.

Suivi pour Linux

Sur Linux, Chromium dépend également d'un certain nombre de bibliothèques système qui peuvent ne pas être présentes. Si le navigateur ne parvient toujours pas à se lancer après la correction standard, installez ces dépendances :

sudo npx playwright@1.60.0 install-deps chromium

Vous pouvez également combiner les deux étapes en une seule commande :

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

Utiliser un navigateur que vous avez déjà

Si vous disposez déjà d'un binaire Chrome/Chromium compatible sur votre hôte, vous pouvez contourner entièrement l'installation de Playwright en définissant la variable d'environnement AXE_CHROME_PATH sur ce binaire. C'est souvent la solution la plus rapide lorsque le téléchargement de Playwright est bloqué (réseau restreint, proxy) ou lorsque l'installation des dépendances système n'est pas une option. Voir AXE_CHROME_PATH pour les exigences — notez que la version stable de Google Chrome 137+ n'est pas prise en charge, et que la valeur doit être un binaire exécutable plutôt qu'un ensemble .app.

Pourquoi Chromium n'est pas inclus

Playwright associe un révision spécifique de Chromium à chaque version de Playwright, et cette révision change avec le temps. L'inclusion d'un binaire de navigateur dans le paquet npm gonflerait considérablement sa taille, l'associerait au binaire d'une seule plateforme, et le rendrait obsolète dès que Playwright mettrait à jour sa révision associée. Installer Chromium via Playwright garantit au contraire que vous obtenez exactement la révision attendue par votre version installée, pour votre plateforme. (La distribution Docker peut inclure un navigateur car l'image est construite pour un environnement unique et connu.)

Relancer après une mise à jour de axe-mcp-server

Mettre à jour axe-mcp-server peut introduire une nouvelle version de Playwright, qui peut associer un révision de Chromium plus récente différent de celui actuellement installé. Dans ce cas, vous pourriez voir de nouveau la même erreur de lancement après une mise à niveau. La solution est la même — relancez l'installation avec la version de Playwright que le serveur mis à jour fournit pour que Chromium corresponde :

npx playwright@1.60.0 install chromium

En règle générale, relancez cette commande — en utilisant la version de Playwright que la version actuelle fournit — chaque fois que vous mettez à jour axe-mcp-server et que le serveur signale une incompatibilité de Chromium au démarrage.

Erreurs d'authentification

Clé API

• Vérifiez que votre clé API est valide et n'a pas expiré
• Assurez-vous que votre abonnement axe Account Portal inclut l'accès au serveur MCP
• Vérifiez que la clé API a été créée pour le produit "axe MCP Server"
• Confirmez que seul AXE_API_KEY est défini — si AXE_ACCESS_TOKEN est également défini, le serveur échouera au démarrage
• Confirmez que votre URL du serveur axe est correcte — si votre organisation utilise une instance axe régionale, privée ou sur site, AXE_SERVER_URL doit être réglé sur l'URL de base de votre instance. Voir Référence de configuration pour les détails.

OAuth

• Confirmez que seul AXE_ACCESS_TOKEN est défini — si AXE_API_KEY est également défini, le serveur échouera au démarrage
• Exécutez npx @deque/axe-auth token dans votre terminal pour confirmer que vous avez un jeton valide ; s'il se termine par un code non nul, réauthentifiez-vous avec npx @deque/axe-auth login
• Confirmez que l'URL de votre serveur axe est correcte
• Si votre jeton a expiré en cours de session, redémarrez la connexion au serveur MCP dans votre client (par exemple, redémarrer Claude Code, basculer le serveur dans les paramètres MCP de Cursor, ou cliquer sur le bouton "Redémarrer" de CodeLens de VS Code directement au-dessus de l'entrée du serveur axe MCP dans mcp.json) pour obtenir un nouveau jeton
• Voir Authentification pour les étapes complètes de dépannage d'OAuth

Obtenir de l'aide

Si vous rencontrez des problèmes non couverts dans cette section de dépannage :

1. Consultez la console de développeur/les journaux de votre client MCP pour obtenir des messages d'erreur détaillés (par exemple, la Console de Développeur de VS Code, les Outils de Développement de Cursor, ou la sortie --debug de Claude Code)
2. Examinez les journaux du serveur — les journaux des conteneurs Docker ou les journaux de votre client MCP lorsque vous utilisez la distribution npm
3. Contactez notre équipe support à helpdesk@deque.com avec :
   • Votre client MCP et sa version
   • Votre version de Docker (distribution Docker) ou version de Node.js (distribution npm)
   • Messages d'erreur complets
   • Étapes pour reproduire le problème