Dépannage

Cette page couvre les problèmes courants dans les distributions Docker et npm. Les problèmes qui concernent une seule 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 ou 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 le 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

L'analyse du serveur de développement local échoue avec ERR_CONNECTION_REFUSED

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

Si l'outil analyze échoue avec une erreur net::ERR_CONNECTION_REFUSED en essayant de scanner un serveur de développement fonctionnant localement, c'est probablement parce que le serveur axe MCP fonctionne dans un conteneur Docker et ne peut pas atteindre les services liés uniquement à localhost (c.-à-d., 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 --host drapeau défini sur 0.0.0.0 afin qu'il écoute sur 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 un docker system prune

Installation de Chromium (npm)

Cette section s'applique à la 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 véritable navigateur 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 fournie par le serveur attend, le serveur échoue au démarrage (ou échoue lors de 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 fournie par le serveur axe MCP — actuellement 1.60.0. Fixez Playwright à cette version afin qu'une simple npx playwright ne résolve pas vers 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 avez déjà un binaire Chrome/Chromium compatible sur votre hôte, vous pouvez éviter complètement 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 Playwright est bloqué (réseau restreint, proxy) ou lorsque l'installation de dépendances système n'est pas envisageable. Voir AXE_CHROME_PATH pour les exigences — notez que Google Chrome stable 137+ de marque n'est pas pris en charge, et la valeur doit être un binaire exécutable plutôt qu'un .app bundle.

Pourquoi Chromium n'est pas inclus

Playwright fixe une révision spécifique de Chromium à chaque version de Playwright, et cette révision change au fil du temps. Inclure un binaire de navigateur dans le package npm gonflerait considérablement sa taille, lierait le package au binaire d'une seule plateforme et deviendrait obsolète dès que Playwright met à jour sa révision fixée. Installer Chromium via Playwright garantit à la place que vous obtenez exactement la révision que votre version installée attend, 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

La mise à niveau de axe-mcp-server peut intégrer une version plus récente de Playwright, qui peut fixer une révision de Chromium plus récente que celle actuellement installée. Lorsque cela se produit, vous pouvez voir à nouveau la même erreur de lancement après une mise à niveau. La solution est la même — réexécutez l'installation avec la version de Playwright que le serveur mis à niveau propose afin que Chromium corresponde :

npx playwright@1.60.0 install chromium

En règle générale, réexécutez cette commande — en utilisant la version de Playwright que la version actuelle propose — chaque fois que vous mettez à niveau 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 l'URL de votre serveur axe est correcte — si votre organisation utilise une instance axe régionale, privée ou sur site, AXE_SERVER_URL doit être défini sur l'URL de base de votre instance. Voir Référence de configuration pour plus de 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 avec 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 milieu de session, redémarrez la connexion au serveur MCP dans votre client (par exemple, en redémarrant Claude Code, en basculant le serveur dans les paramètres MCP de Cursor, ou en cliquant sur le bouton "Redémarrer" de CodeLens directement au-dessus de l'entrée axe MCP Server dans mcp.json) pour obtenir un nouveau jeton
• Voir Authentification pour des étapes complètes de dépannage OAuth

Obtenir de l'aide

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

1. Vérifiez la console développeur de VS Code pour des messages d'erreur détaillés
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 d'assistance à l'adresse helpdesk@deque.com avec :
   • Votre version de VS Code
   • Votre version de Docker (distribution Docker) ou version de Node.js (distribution npm)
   • Messages d'erreur complets
   • Étapes pour reproduire le problème