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 en ambas Docker y npm. Los problemas que se 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 de 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 al soporte si es necesario)

Tiempos de espera de escaneo

  • Asegúrese de que la URL de destino sea accesible desde su red
  • Verifique problemas de conectividad de red
  • Aumente el tiempo de espera para la fase que realmente expiró. Cada uno es un presupuesto independiente, por lo que aumentar el incorrecto no cambia nada. Coincida con el texto de error que recibió, luego vea Opciones de Configuración para los valores predeterminados:
Menciones de error Aumentar
Axe scan timed out after BROWSER_TIMEOUT_MS
IGT timed out after IGT_TIMEOUT_MS
Un tiempo de espera en una llamada remediate REMEDIATE_TIMEOUT_MS

Un Prueba Guiada Inteligente que expira no falla la llamada analyze circundante: los resultados de axe aún regresan, con la falla reportada bajo el propio status de esa prueba.

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 host y puede acceder a los servicios localhost normalmente.

Si la herramienta analyze falla con un error net::ERR_CONNECTION_REFUSED al intentar escanear un servidor de desarrollo que se está ejecutando localmente, es probable que esto se deba a que el servidor Axe MCP se ejecuta dentro de un contenedor Docker y no puede alcanzar los servicios vinculados 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 opción --host configurada en 0.0.0.0 para que escuche en todas las interfaces de red, haciéndolo accesible desde dentro del contenedor Docker:

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

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

Las reglas avanzadas no se ejecutaron

Verifique primero el bloque advancedRules en la respuesta analyze — su campo source nombra la razón:

source Qué hacer
org_default No hay nada mal. Si value es disabled, su administrador estableció eso como la configuración predeterminada de la organización en Configuración de Axe.
org_policy_locked Su administrador bloqueó la configuración. Las anulaciones se ignoran por diseño — pídele que verifique "Permitir que los usuarios cambien".
unavailable Las reglas avanzadas no están disponibles para este servidor, o la Configuración de Axe no devolvió ningún valor utilizable para ellas.

Otras cosas a verificar:

  • El parámetro advancedRules no lo ofrece su agente. La herramienta analyze solo lo ofrece cuando las reglas avanzadas están disponibles para su organización. Reinicie la conexión del servidor MCP para que su cliente vuelva a leer la lista de herramientas después de que cambien sus accesos.
  • AXE_ADVANCED_RULES no tuvo efecto. Confirme que el servidor realmente se inició con él (un error tipográfico falla el inicio — vea AXE_ADVANCED_RULES), y que un argumento advancedRules por llamada no tome precedencia.
  • Faltan hallazgos avanzados en data. Los hallazgos avanzados que degradaron a necesita revisión se filtran a menos que Predeterminado Necesita Revisión esté habilitado en Configuración de Axe. Verifique el array messages de la respuesta para un mensaje de degradación.
  • Los escaneos se agotan después de habilitar las Reglas Avanzadas. Agregan aproximadamente 15–20 segundos por escaneo. Aumente BROWSER_TIMEOUT_MS.
  • Las reglas avanzadas dejaron de ejecutarse a mitad de sesión. Si Deque rechaza un escaneo porque las reglas avanzadas no están disponibles para su organización, el servidor deja de intentar ejecutarlas para el resto de ese proceso. Reinícielo después de un cambio de suscripción.

Vea Reglas Avanzadas para la referencia completa.

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 mediante el control de un navegador real a través de Playwright. Con la distribución 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 con la que el servidor se distribuye, el servidor no se inicia (o falla en el primer escaneo) con un error indicando que no se pudo lanzar Chromium.

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

Corrección estándar

tip

El mensaje de error es la fuente más confiable. Nombra el comando exacto anclado para el servidor que está ejecutando — ejecute eso literalmente. Los comandos a continuación derivan el mismo pin de la última versión publicada, lo cual es correcto a menos que esté anclado a una axe-mcp-server más antigua.

Instale la revisión de Chromium que coincida con la versión de Playwright con la que se distribuye el servidor Axe MCP. Playwright debe estar fijado, por lo que un simple npx playwright no se resuelve en una nueva versión con una revisión de Chromium que el servidor no soporte:

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

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

Si ejecuta un servidor más antiguo anclado, sustituya su versión — npm view axe-mcp-server@<version> dependencies.playwright — o tome el pin del mensaje de error. Al momento de escribir esto, la versión 1.4.0 del servidor envía Playwright 1.61.1.

En Windows cmd.exe, que no tiene sustitución de $(...), ejecute npm view axe-mcp-server dependencies.playwright por separado e inserte la versión. PowerShell, Git Bash y WSL manejan los comandos tal cual.

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

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

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

Use un navegador que ya tenga

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

Por qué Chromium no está incluido

Playwright fija un 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 inflaría significativamente su tamaño, vincularía el paquete a un binario de una plataforma y quedaría obsoleto tan pronto como Playwright actualizara su revisión fija. 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 entorno único y conocido.)

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

Actualizar axe-mcp-server puede incorporar una versión más nueva de Playwright, la cual puede fijar un revisión más reciente de Chromium diferente al que está actualmente instalado. Cuando eso suceda, es posible que vea 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 incluye el servidor actualizado para que Chromium coincida:

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

Debido a que el pin se deriva en lugar de ser codificado, el mismo comando se mantiene correcto a través de actualizaciones. Vuelva a ejecutarlo cada vez que actualice axe-mcp-server y el servidor informe un desajuste de Chromium al inicio.

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 de Axe incluya acceso al servidor MCP
  • Verifique que la clave API se haya creado para el producto "Axe MCP Server"
  • Confirme que solo se haya configurado AXE_API_KEY — si también está configurado AXE_ACCESS_TOKEN, el servidor fallará al iniciar
  • Confirme que la URL de su servidor Axe sea correcta. Si su organización utiliza una instancia de Axe regional, en la nube privada o en las instalaciones, AXE_SERVER_URL debe estar configurado con la URL base de su instancia. Consulte Referencia de Configuración para más detalles.

OAuth

  • Confirme que solo se haya configurado AXE_ACCESS_TOKEN — si también está configurado AXE_API_KEY, el servidor fallará al iniciar
  • Ejecute npx @deque/axe-auth token en su terminal para confirmar que tiene un token válido; si termina con un código distinto de cero, vuelva a autenticarse con npx @deque/axe-auth login
  • Confirme que la URL de su servidor Axe sea correcta
  • Si su token expira a mitad de sesión, su configuración está capturando un solo token al inicio. Inicie el servidor a través de @deque/axe-auth run en su lugar, lo que actualiza el token del servidor en ejecución por usted — vea Manteniendo una sesión larga activa
  • Si axe-auth run informa que la actualización del token no pudo alcanzar el servidor, el puerto de actualización no coincide: verifique que AXE_TOKEN_REFRESH_PORT y la publicación de Docker -p 127.0.0.1:<port>:<port> nombren el mismo puerto, y que el contenedor configure AXE_TOKEN_REFRESH_HOST=0.0.0.0. Vea Variables de actualización de token
  • Consulte Autenticación para ver los pasos completos de 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/descripción de errores del desarrollador de su cliente MCP para obtener mensajes de error detallados (por ejemplo, la consola de desarrollador de VS Code, las herramientas de desarrollo de Cursor, o la salida de --debug de Claude Code)
  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 cliente MCP y su versión
    • 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?