Resolución de problemas

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

Esta página cubre problemas comunes tanto en las distribuciones de Docker y npm. Los problemas que aplican solo a una distribución están etiquetados en consecuencia.

El servidor no se inicia

  • Asegúrese de que Docker esté en funcionamiento (distribución de Docker), o que Chromium esté instalado (distribución de npm — vea instalación de Chromium)
  • Verifique que sus credenciales sean correctas: ya sea su AXE_API_KEY o su AXE_ACCESS_TOKEN, pero no ambas (el servidor falla al inicio si ambas están configuradas)
  • Verifique que tenga acceso al servidor axe MCP (contacte con soporte si es necesario)

Tiempos de espera de escaneo

  • Aumente BROWSER_TIMEOUT_MS para páginas complejas
  • Asegúrese de que la URL de destino sea accesible desde su red
  • Verifique problemas de conectividad de red

El escaneo del servidor de desarrollo local falla con ERR_CONNECTION_REFUSED

Esto se aplica a la distribución de Docker — con la distribución de npm el servidor se ejecuta directamente en su anfitrión y puede acceder a localhost los servicios normalmente.

Si la herramienta analyze falla con un error de net::ERR_CONNECTION_REFUSED mientras intenta escanear un servidor de desarrollo que se ejecuta localmente, es probable que se deba a que el servidor axe MCP se ejecuta dentro de un contenedor de Docker y no puede acceder a los servicios enlazados solo a localhost (es decir, 127.0.0.1) en su máquina anfitriona.

**Ejemplo de error**:

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

**Solución**: Inicie su servidor de desarrollo con la bandera --host configurada en 0.0.0.0 para que escuche en todas las interfaces de red, haciéndolo accesible desde dentro del contenedor de Docker:

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

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

Problemas con Docker

  • Asegúrese de que el demonio de Docker esté en ejecución
  • Verifique los permisos de Docker
  • Verifique la conectividad de red para las descargas de imágenes de Docker
  • Asegúrese de que Docker tenga suficiente memoria ejecutando un docker system prune

Instalación de Chromium (npm)

Esta sección se aplica a la distribución de npm. La distribución de Docker incluye su propio navegador, por lo que los usuarios de Docker no necesitan instalar Chromium y no se ven afectados por los errores descritos aquí.

Qué significa el error

El servidor axe MCP realiza escaneos de accesibilidad controlando un navegador real a través de Playwright. Con la distribución de npm, ese navegador — Chromium — debe estar instalado en su anfitrión. Si falta, o si la versión instalada no coincide con la revisión de Chromium que espera la versión de Playwright que envía el servidor, el servidor no se inicia (o falla en el primer escaneo) con un error que indica que Chromium no pudo lanzarse.

Esto se espera en una instalación nueva y es sencillo de arreglar.

Corrección estándar

Instale la revisión de Chromium que coincide con la versión de Playwright que envía el servidor axe MCP — actualmente 1.60.0. Fije Playwright a esa versión para que una instalación npx playwright no se resuelva a una nueva versión con una revisión de Chromium que el servidor no soporta:

npx playwright@1.60.0 install chromium

Luego reinicie el servidor MCP (o su cliente MCP) e intente de nuevo.

Seguimiento en Linux

En Linux, Chromium también depende de una serie de bibliotecas del sistema que pueden no estar presentes. Si el navegador aún falla al iniciar después de la solución estándar, instale esas dependencias:

sudo npx playwright@1.60.0 install-deps chromium

También puede combinar ambos pasos en un solo comando:

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

Use un navegador que ya tenga

Si ya tiene un binario compatible de Chrome/Chromium en su host, puede evitar la instalación de Playwright completamente configurando la AXE_CHROME_PATH variable de entorno a ese binario. Esta es a menudo la solución más rápida cuando la descarga de Playwright está bloqueada (red restringida, proxy) o cuando instalar dependencias del sistema no es posible. Vea AXE_CHROME_PATH para los requisitos — note que la versión estable 137+ de Google Chrome con marca no está soportada, y el valor debe ser un binario ejecutable en lugar de un .app paquete.

Por qué Chromium no está incluido

Playwright fija una revisión específica de Chromium a cada versión de Playwright, y esa revisión cambia con el tiempo. Incluir un binario del navegador en el paquete npm aumentaría significativamente su tamaño, ataría el paquete al binario de una plataforma y se volvería obsoleto tan pronto como Playwright actualizara su revisión fijada. Instalar Chromium a través de Playwright garantiza que obtenga exactamente la revisión que su versión instalada espera, para su plataforma. (La distribución de Docker puede incluir un navegador porque la imagen está construida para un único entorno conocido.)

Re-ejecutando después de una actualización de axe-mcp-server

Actualizar axe-mcp-server puede traer una versión más reciente de Playwright, que puede fijar una revisión más reciente de Chromium que la actualmente instalada. Cuando eso sucede, puede ver el mismo error de inicio nuevamente después de una actualización. La solución es la misma: vuelva a ejecutar la instalación con la versión de Playwright que el servidor actualizado trae para que Chromium coincida:

npx playwright@1.60.0 install chromium

Como regla general, vuelva a ejecutar este comando — usando la versión de Playwright que la versión actual incluye — cada vez que actualice axe-mcp-server y el servidor informa un desajuste de Chromium al iniciar.

Errores de autenticación

Clave de API

  • Verifique que su clave de API sea válida y no haya expirado
  • Asegúrese de que su suscripción al Portal de Cuentas axe incluya acceso al Servidor MCP
  • Compruebe que la clave de API fue creada para el producto "axe MCP Server"
  • Confirme que solo AXE_API_KEY está configurado — si AXE_ACCESS_TOKEN también está configurado, el servidor fallará al iniciar
  • Confirme que la URL de su servidor axe es correcta — si su organización usa una instancia de axe regional, nube privada o local, AXE_SERVER_URL debe configurarse con la URL base de su instancia. Vea Referencia de Configuración para más detalles.

OAuth

  • Confirme que solo AXE_ACCESS_TOKEN está configurado — si AXE_API_KEY también está configurado, el servidor fallará al iniciar
  • Ejecute npx @deque/axe-auth token en su terminal para confirmar que tiene un token válido; si sale con un código no cero, vuelva a autenticarse con npx @deque/axe-auth login
  • Confirme que la URL de su servidor axe es correcta
  • Si su token ha expirado en mitad de la sesión, reinicie la conexión del servidor MCP en su cliente (por ejemplo, reiniciando Claude Code, desactivando y reactivando el servidor en la configuración MCP de Cursor, o haciendo clic en el botón "Reiniciar" de CodeLens de VS Code directamente sobre la entrada del Servidor MCP de axe en mcp.json) para obtener un nuevo token
  • Vea Autenticación para pasos completos sobre solución de problemas de OAuth

Obteniendo ayuda

Si encuentra problemas no cubiertos en esta sección de solución de problemas:

  1. Revise la Consola de Desarrollador de VS Code para mensajes de error detallados
  2. Revise los registros del servidor: los registros del contenedor Docker o los registros de su cliente MCP al usar la distribución de npm
  3. Contacte a nuestro equipo de soporte en helpdesk@deque.com con:
    • Su versión de VS Code
    • Su versión de Docker (distribución de Docker) o versión de Node.js (distribución de npm)
    • Mensajes de error completos
    • Pasos para reproducir el problema

Is this page helpful?

Help us improve this page

Still need help?