Resolução 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 aborda problemas comuns em ambas as Docker e npm. Problemas que se aplicam a apenas uma distribuição são rotulados de acordo.

Servidor não inicia

  • Certifique-se de que o Docker está em execução (distribuição Docker), ou que o Chromium está instalado (distribuição npm — veja instalação do Chromium)
  • Verifique se suas credenciais estão corretas: ou seu AXE_API_KEY ou seu AXE_ACCESS_TOKEN, mas não ambos (o servidor falha na inicialização se ambos estiverem definidos)
  • Verifique se você tem acesso ao servidor axe MCP (contate o suporte se necessário)

Tempo limite de varredura

  • Aumente BROWSER_TIMEOUT_MS para páginas complexas
  • Certifique-se de que o URL de destino é acessível a partir da sua rede
  • Verifique problemas de conectividade de rede

Falha na verificação do servidor de desenvolvimento local com ERR_CONNECTION_REFUSED

Isso se aplica ao distribuição Docker — com a distribuição npm o servidor é executado diretamente no seu host e pode acessar serviços localhost normalmente.

Se a ferramenta analyze falhar com um erro net::ERR_CONNECTION_REFUSED ao tentar verificar um servidor de desenvolvimento em execução localmente, isso provavelmente ocorre porque o axe MCP Server é executado dentro de um contêiner Docker e não pode acessar serviços vinculados apenas ao localhost (ou seja, 127.0.0.1) no seu host.

Exemplo de erro:

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

Solução: Inicie seu servidor de desenvolvimento com a flag --host definida para 0.0.0.0 para que ele escute em todas as interfaces de rede, tornando-o acessível a partir de dentro do contêiner Docker:

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

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

Regras Avançadas não foram executadas

Verifique primeiro o bloco advancedRules na resposta analyze — seu campo source nomeia a razão:

source O que fazer
org_default Não há nada errado. Se value é disabled, seu administrador definiu isso como o padrão da organização em Configuração do axe.
org_policy_locked Seu administrador trancou a configuração. Substituições são ignoradas por padrão — peça a ele para verificar "Permitir que os usuários alterem".
unavailable As Regras Avançadas não estão disponíveis para este servidor, ou a Configuração do axe não retornou um valor utilizável para elas.

Outras coisas a verificar:

  • O parâmetro advancedRules não é oferecido pelo seu agente. A ferramenta analyze só a oferece quando as Regras Avançadas estão disponíveis para sua organização. Reinicie a conexão do servidor MCP para que seu cliente releia a lista de ferramentas após suas alterações de acesso.
  • AXE_ADVANCED_RULES não teve efeito. Confirme que o servidor realmente iniciou com ela (um erro de digitação impede a inicialização — veja AXE_ADVANCED_RULES), e que um argumento advancedRules por chamada não está tendo precedência.
  • Encontraram-se ausentes de data os achados avançados. Os achados avançados que foram degradados para necessitar de revisão são filtrados, a menos que Padrão Precisa de Revisão esteja habilitado em Configuração do axe. Verifique a mensagem de degradação no array messages da resposta.
  • As verificações expiram após a ativação das Regras Avançadas. Elas adicionam aproximadamente 15–20 segundos por verificação. Aumente BROWSER_TIMEOUT_MS.
  • As Regras Avançadas pararam de ser executadas no meio da sessão. Se a Deque rejeitar uma verificação por as Regras Avançadas não estarem disponíveis para sua organização, o servidor deixará de tentar executá-las pelo resto desse processo. Reinicie-o após uma mudança de assinatura.

Veja Regras Avançadas para a referência completa.

Problemas com Docker

  • Certifique-se de que o daemon do Docker está em execução
  • Verifique as permissões do Docker
  • Verifique a conectividade de rede para downloads de imagens do Docker
  • Certifique-se de que o Docker tem memória suficiente executando um docker system prune

Instalação do Chromium (npm)

Esta seção se aplica ao distribuição npm. A distribuição Docker inclui seu próprio navegador, portanto, os usuários do Docker não precisam instalar o Chromium e não são afetados pelos erros descritos aqui.

O que o erro significa

O axe MCP Server executa varreduras de acessibilidade dirigindo um navegador real através de Playwright. Com a distribuição npm, esse navegador — o Chromium — deve estar instalado no seu host. Se estiver ausente, ou se a versão instalada não corresponder à revisão do Chromium que a versão do Playwright que o servidor envia espera, o servidor falha ao iniciar (ou falha na primeira verificação) com um erro indicando que o Chromium não pôde ser lançado.

Isso é esperado em uma instalação nova e é fácil de corrigir.

Correção padrão

tip

A mensagem de erro é a fonte mais confiável. Ela nomeia o comando fixado exato para o servidor que você está realmente executando — execute-o literalmente. Os comandos abaixo derivam o mesmo fixo da última versão publicada, o que é correto, a menos que você esteja fixado em uma versão axe-mcp-server mais antiga.

Instale a revisão do Chromium que corresponde à versão do Playwright que o servidor MCP do axe entrega. O Playwright deve ser fixado, então um simples npx playwright não se resolve para uma versão mais recente com uma revisão do Chromium que o servidor não suporta:

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

Em seguida, reinicie o servidor MCP (ou seu cliente MCP) e tente novamente.

Se você executar um servidor mais antigo fixado, substitua sua versão — npm view axe-mcp-server@<version> dependencies.playwright — ou pegue o fixo da mensagem de erro. No momento da redação, a versão do servidor 1.4.0 entrega o Playwright 1.61.1.

No Windows cmd.exe, que não tem substituição para $(...), execute npm view axe-mcp-server dependencies.playwright separadamente e insira a versão. PowerShell, Git Bash e WSL lidam com os comandos como escritos.

Complemento para Linux

No Linux, o Chromium também depende de várias bibliotecas do sistema que podem não estar presentes. Se o navegador ainda falhar ao iniciar após a correção padrão, instale essas dependências:

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

Você também pode combinar ambos os passos em um único comando:

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

Use um navegador que você já possui

Se já tiver um binário compatível do Chrome/Chromium no seu host, você pode evitar a instalação do Playwright completamente definindo a variável de ambiente AXE_CHROME_PATH para esse binário. Este é frequentemente o ajuste mais rápido quando o download do Playwright está bloqueado (rede restrita, proxy) ou quando instalar dependências do sistema não é uma opção. Veja AXE_CHROME_PATH para os requisitos — note que o Google Chrome estável 137+ não é suportado, e o valor deve ser um binário executável em vez de um pacote .app.

Por que o Chromium não está incluído

O Playwright fixa uma revisão específica do Chromium para cada versão do Playwright, e essa revisão muda com o tempo. Incorporar um binário de navegador no pacote npm inflaria significativamente seu tamanho, amarraria o pacote a um binário de uma plataforma e ficaria obsoleto assim que o Playwright atualizasse sua revisão fixada. Instalar o Chromium através do Playwright, em vez disso, garante que você obtenha exatamente a revisão que sua versão instalada espera, para sua plataforma. (A distribuição Docker pode embutir um navegador porque a imagem é construída para um ambiente único e conhecido.)

Reexecutando após uma atualização do axe-mcp-server

Atualizar axe-mcp-server pode trazer uma versão mais recente do Playwright, que pode fixar uma revisão mais recente do Chromium diferente da atualmente instalada. Quando isso acontece, você pode ver o mesmo erro de lançamento novamente após uma atualização. A solução é a mesma — executar novamente a instalação com a versão do Playwright que o servidor atualizado envia para que o Chromium corresponda:

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

Como o fixo é derivado e não codificado rigidamente, o mesmo comando permanece correto em todas as atualizações. Execute-o novamente sempre que você atualizar axe-mcp-server e o servidor relatar uma incompatibilidade do Chromium na inicialização.

Erros de autenticação

Chave de API

  • Verifique se a sua chave de API é válida e não expirou
  • Certifique-se de que sua assinatura do Portal de Conta axe inclui acesso ao Servidor MCP
  • Verifique se a chave de API foi criada para o produto "axe MCP Server"
  • Confirme que apenas AXE_API_KEY está definido — se AXE_ACCESS_TOKEN também estiver definido, o servidor falhará na inicialização
  • Confirme que a URL do seu servidor axe está correta — se sua organização usa uma instância regional, nuvem privada ou on-premises do axe, AXE_SERVER_URL deve ser definido para a URL base da sua instância. Veja Referência de Configuração para detalhes.

OAuth

  • Confirme que apenas AXE_ACCESS_TOKEN está definido — se AXE_API_KEY também estiver definido, o servidor falhará na inicialização
  • Execute npx @deque/axe-auth token no seu terminal para confirmar se você tem um token válido; se ele sair com um código diferente de zero, reautentique com npx @deque/axe-auth login
  • Confirme que o URL do servidor axe está correto
  • Se seu token expirar no meio da sessão, sua configuração está capturando um único token na inicialização. Inicie o servidor por meio de @deque/axe-auth run em vez disso, o que atualiza o token do servidor em execução para você — veja Mantendo uma sessão longa ativa
  • Se axe-auth run relatar que a atualização do token não pôde alcançar o servidor, a porta de atualização não está alinhada: verifique se AXE_TOKEN_REFRESH_PORT e o nome de publicação do Docker -p 127.0.0.1:<port>:<port> nomeiam a mesma porta e se o container define AXE_TOKEN_REFRESH_HOST=0.0.0.0. Veja Variáveis de atualização do token
  • Veja Autenticação para etapas completas de solução de problemas do OAuth

Obtendo Ajuda

Se você encontrar problemas não cobertos nesta seção de solução de problemas:

  1. Verifique o console/desenvolvedor do seu cliente MCP para mensagens de erro detalhadas (por exemplo, o Console de Desenvolvedor do VS Code, as Ferramentas de Desenvolvedor do Cursor, ou a saída --debug do Claude Code)
  2. Revise os logs do servidor — os logs do contêiner Docker, ou os logs do seu cliente MCP ao usar a distribuição npm
  3. Entre em contato com nossa equipe de suporte em helpdesk@deque.com com:
    • Seu cliente MCP e sua versão
    • Sua versão do Docker (distribuição Docker) ou a versão do Node.js (distribuição npm)
    • Mensagens de erro completas
    • Passos para reproduzir o problema

Is this page helpful?

Help us improve this page

Still need help?