Risoluzione dei problemi

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

Questa pagina copre problemi comuni per entrambe le Docker che npm. I problemi che riguardano solo una distribuzione sono contrassegnati di conseguenza.

Il server non si avvia

  • Assicurarsi che Docker sia in esecuzione (distribuzione Docker) o che Chromium sia installato (distribuzione npm — vedi installazione di Chromium)
  • Verificare che le credenziali siano corrette: o il tuo AXE_API_KEY o il tuo AXE_ACCESS_TOKEN, ma non entrambi (il server fallisce all'avvio se entrambi sono impostati)
  • Verifica di avere accesso al server Axe MCP (contatta il supporto se necessario)
  • Leggi l'errore di avvio: nomina l'impostazione che è sbagliata, come un URL proxy non valido o un AXE_CHROME_PATH che non può essere avviato, e spiega il motivo
  • Su una rete che consente il traffico in uscita solo tramite un proxy, consulta Proxy aziendale

Timeout durante la scansione

  • Assicurarsi che l'URL di destinazione sia accessibile dalla rete
  • Controllare eventuali problemi di connettività di rete
  • Aumenta il timeout per la fase che è effettivamente scaduta. Ognuna è un budget indipendente, quindi aumentare quello sbagliato non cambia nulla. Abbina il testo di errore che hai ricevuto, quindi consulta Opzioni di configurazione per i valori predefiniti:
Menzioni di errore Aumenta
Axe scan timed out after BROWSER_TIMEOUT_MS
IGT timed out after IGT_TIMEOUT_MS
Una chiamata remediate che scade REMEDIATE_TIMEOUT_MS

Un Test guidato intelligente che scade non fallisce la chiamata analyze circostante: i risultati dell'axe arrivano comunque, con il fallimento riportato sotto il proprio status di quel test.

Il controllo del server di sviluppo locale fallisce con ERR_CONNECTION_REFUSED

Questo si applica alla distribuzione Docker — con la distribuzione npm il server funziona direttamente sul tuo host e può raggiungere normalmente i servizi localhost.

Se lo strumento analyze fallisce con un errore net::ERR_CONNECTION_REFUSED durante il tentativo di controllare un server di sviluppo in esecuzione localmente, probabilmente è perché Axe MCP Server funziona all'interno di un container Docker e non può raggiungere i servizi associati solo a localhost (cioè, 127.0.0.1) sulla tua macchina host.

Esempio di errore:

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

Soluzione: Avvia il tuo server di sviluppo con il flag --host impostato su 0.0.0.0 per farlo ascoltare su tutte le interfacce di rete, rendendolo raggiungibile dall'interno del container Docker:

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

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

Certificati non attendibili

Se una scansione fallisce con net::ERR_CERT_AUTHORITY_INVALID, il browser della scansione non si fida dell'autorità di certificazione (CA) che ha firmato il certificato della pagina. Questo è comune per i siti intranet firmati da una CA interna e sulle reti con un proxy che ispeziona il traffico TLS. Il tuo agente fornisce la soluzione per la tua piattaforma:

  • Docker e npm su Linux — imposta NODE_EXTRA_CA_CERTS sul percorso del certificato CA (formato PEM), quindi riavvia il server. Su Docker, monta anche il file nel contenitore. Su npm, installa prima certutil (libnss3-tools su Debian/Ubuntu, nss-tools su RHEL/Fedora).
  • npm su macOS — aggiungi la CA al tuo portachiavi di login, fidati solo per SSL.
  • npm su Windows — aggiungi la CA al tuo store Radice di Fiducia dell'Utente Corrente, fidati solo per SSL.

Su macOS e Windows, il browser rileva la modifica alla scansione successiva, senza bisogno di riavvio.

Se hai già impostato NODE_EXTRA_CA_CERTS e le scansioni continuano a fallire, controlla il registro di avvio del server per un avviso riguardante il certificato, come certutil che non è installato, o il file che contiene più di un certificato quando solo il primo è aggiunto al browser. Se il file non esiste o non può essere letto, il server non si avvia affatto, e l'errore di avvio lo indica.

Questo si applica solo a una CA non attendibile. Certificati scaduti, revocati o con nome host errato sono problemi del certificato del sito stesso, e aggiungere una CA non li risolve.

Se non puoi aggiungere la CA, NODE_TLS_REJECT_UNAUTHORIZED disattiva completamente i controlli dei certificati. Usalo solo per il test locale, e prova prima NODE_EXTRA_CA_CERTS.

Proxy aziendale

Se la tua rete consente il traffico in uscita solo tramite un proxy, il server non può raggiungere il server axe, quindi fallisce all'avvio o durante la convalida delle tue credenziali. Imposta HTTPS_PROXY sull'URL completo del proxy. Consulta Variabili proxy.

Se usi OAuth 2.0, imposta anche NODE_USE_ENV_PROXY=1 in modo che il CLI di @deque/axe-auth ti connetta e aggiorni i token tramite il proxy. Questo richiede Node.js 22.21 o successivo. Consulta Variabili proxy.

  • Le pagine intranet non si caricano nelle scansioni: il browser della scansione utilizza anche il proxy. Aggiungi quegli host a NO_PROXY.
  • Il server registra un avviso sulle credenziali del proxy: il browser della scansione non può utilizzare un proxy che richiede un nome utente e una password. Chiedi al tuo team di rete un endpoint proxy che non li richieda, o uno che permetta il traffico del browser della scansione.
  • Le richieste falliscono con errori di certificato una volta impostato il proxy: il proxy sta ispezionando il traffico TLS. Imposta anche NODE_EXTRA_CA_CERTS sul certificato CA del proxy.

Le regole avanzate non sono state eseguite

Controlla prima il blocco advancedRules nella risposta analyze — il campo source nomina il motivo:

source Cosa fare
org_default Non c'è nulla di sbagliato. Se value è disabled, il tuo amministratore lo ha impostato come predefinito dell'organizzazione in Configurazione di Axe.
org_policy_locked Il tuo amministratore ha bloccato l'impostazione. Le sovrascritture sono ignorate di proposito — chiedi loro di verificare "Consenti agli utenti di cambiare".
unavailable Le Regole Avanzate non sono disponibili per questo server, o la Configurazione di Axe non ha restituito un valore utilizzabile per esse.

Altre cose da controllare:

  • Il parametro advancedRules non è offerto dal tuo agente. Lo strumento analyze lo offre solo quando le Regole Avanzate sono disponibili per la tua organizzazione. Riavvia la connessione al server MCP affinché il tuo client rileggi l'elenco degli strumenti dopo che l'accesso cambia.
  • AXE_ADVANCED_RULES non ha avuto effetto. Conferma che il server sia effettivamente avviato con esso (un errore di battitura interrompe l'avvio — vedi AXE_ADVANCED_RULES), e che un argomento per chiamata advancedRules non prenda il sopravvento.
  • I risultati avanzati mancano da data. I risultati avanzati che sono degradati a necessitano revisione sono filtrati a meno che Predefinito Necessita di Revisione sia abilitato in Configurazione di Axe. Controlla l'array messages della risposta per un messaggio di degrado.
  • Le scansioni scadono dopo l'abilitazione delle Regole Avanzate. Aggiungono circa 15-20 secondi per scansione. Aumenta BROWSER_TIMEOUT_MS.
  • Le regole avanzate hanno smesso di funzionare a metà sessione. Se Deque rifiuta una scansione perché le Regole Avanzate non sono disponibili per la tua organizzazione, il server smette di tentarle per il resto di quel process. Riavvialo dopo un cambio di abbonamento.

Vedi Regole Avanzate per la referenza completa.

Problemi con Docker

  • Assicurarsi che il daemon Docker sia in esecuzione
  • Controllare i permessi di Docker
  • Verificare la connettività di rete per i download delle immagini Docker
  • Assicurarsi che Docker abbia abbastanza memoria eseguendo un docker system prune

Installazione di Chromium (npm)

Questa sezione si applica alla distribuzione npm. La distribuzione Docker include il proprio browser, quindi gli utenti Docker non hanno bisogno di installare Chromium e non sono influenzati dagli errori qui descritti.

Cosa significa l'errore

Il server Axe MCP esegue le scansioni di accessibilità tramite un vero browser attraverso Playwright. Con la distribuzione npm, quel browser — Chromium — deve essere installato sul tuo host. Se manca, o se la versione installata non corrisponde alla revisione di Chromium che la versione di Playwright fornita dal server si aspetta, il server non riesce ad avviarsi (o fallisce alla prima scansione) con un errore che indica che Chromium non può essere avviato.

Questo è previsto in una nuova installazione ed è semplice da risolvere.

Soluzione standard

tip

Il messaggio di errore è la fonte più affidabile. Nomina il comando esatto bloccato per il server che stai effettivamente eseguendo — eseguilo come è. I comandi seguenti derivano lo stesso blocco dall'ultima versione pubblicata, che è corretta a meno che tu non sia bloccato su un axe-mcp-server più vecchio.

Installa la revisione di Chromium corrispondente alla versione di Playwright fornita dal server Axe MCP. Playwright deve essere fissato, quindi una semplice npx playwright non risolve una nuova versione con una revisione di Chromium che il server non supporta:

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

Poi riavvia il server MCP (o il tuo client MCP) e riprova.

Se esegui un server più vecchio bloccato, sostituisci la sua versione — npm view axe-mcp-server@<version> dependencies.playwright — o prendi il blocco dal messaggio di errore. Al momento della scrittura, la versione del server 1.4.0 fornisce Playwright 1.61.1.

Su Windows cmd.exe, che non ha sostituzione $(...), esegui npm view axe-mcp-server dependencies.playwright separatamente e incolla la versione. PowerShell, Git Bash e WSL gestiscono i comandi come scritti.

Seguito Linux

Su Linux, Chromium dipende anche da un numero di librerie di sistema che potrebbero non essere presenti. Se il browser continua a non avviarsi dopo la correzione standard, installa quelle dipendenze:

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

Puoi anche combinare entrambi i passaggi in un unico comando:

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

Usa un browser che hai già

Se hai già un binario di Chrome/Chromium compatibile sul tuo host, puoi evitare completamente l'installazione di Playwright impostando la variabile d'ambiente AXE_CHROME_PATH a quel binario. Questa è spesso la soluzione più rapida quando il download di Playwright è bloccato (rete limitata, proxy) o quando l'installazione delle dipendenze di sistema non è un'opzione. Vedi AXE_CHROME_PATH per i requisiti — nota che Google Chrome stabile con marchio 137+ non è supportato e il valore deve essere un binario eseguibile piuttosto che un pacchetto .app.

Perché Chromium non è incluso

Playwright associa un revisione specifica di Chromium a ciascuna versione di Playwright, e quella revisione cambia nel tempo. Includere un binario del browser nel pacchetto npm aumenterebbe significativamente la dimensione, legherebbe il pacchetto al binario di una singola piattaforma e diventerebbe obsoleto non appena Playwright aggiornasse la sua revisione fissata. Installare Chromium tramite Playwright garantisce invece di ottenere esattamente la revisione che la tua versione installata si aspetta, per la tua piattaforma. (La distribuzione Docker può includere un browser perché l'immagine è costruita per un ambiente unico e noto.)

Re-esecuzione dopo un aggiornamento di axe-mcp-server

Aggiornare axe-mcp-server potrebbe portare a una versione più recente di Playwright, che può fissare un revisione più recente di Chromium diverso da quello attualmente installato. Quando ciò accade, potresti vedere nuovamente lo stesso errore di avvio dopo un aggiornamento. La soluzione è la stessa: rilancia l'installazione con la versione di Playwright fornita dal server aggiornato affinché Chromium sia compatibile:

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

Poiché il blocco è derivato piuttosto che codificato, lo stesso comando resta corretto in occasione degli aggiornamenti. Rieseguilo ogni volta che aggiorni axe-mcp-server e il server segnala una discrepanza Chromium all'avvio.

Errori di autenticazione

Chiave API

  • Verifica che la tua chiave API sia valida e non sia scaduta
  • Assicurati che l'abbonamento al tuo Portale Account Axe includa l'accesso al server MCP
  • Controlla che la chiave API sia stata creata per il prodotto "Axe MCP Server"
  • Conferma che solo AXE_API_KEY sia impostato — se anche AXE_ACCESS_TOKEN è impostato, il server fallirà all'avvio
  • Conferma che l'URL del tuo server Axe sia corretto — se la tua organizzazione utilizza un'istanza di Axe regionale, cloud privato o on-premise, AXE_SERVER_URL deve essere impostato sull'URL base della tua istanza. Vedi Riferimento alla Configurazione per i dettagli.

OAuth

  • Conferma che solo AXE_ACCESS_TOKEN sia impostato — se anche AXE_API_KEY è impostato, il server fallirà all'avvio
  • Esegui npx @deque/axe-auth token nel tuo terminale per confermare di avere un token valido; se termina con un codice diverso da zero, ri-autenticati con npx @deque/axe-auth login
  • Conferma che l'URL del tuo server Axe sia corretto
  • Se il tuo token scade a metà sessione, la tua configurazione sta catturando un singolo token all'avvio. Avvia il server tramite @deque/axe-auth run invece, che aggiorna il token del server in esecuzione per te — vedi Mantenere una sessione lunga attiva
  • Se axe-auth run segnala che l'aggiornamento del token non ha potuto raggiungere il server, la porta di aggiornamento non corrisponde: verifica che AXE_TOKEN_REFRESH_PORT e il nome di pubblicazione Docker -p 127.0.0.1:<port>:<port> siano la stessa porta, e che il container imposti AXE_TOKEN_REFRESH_HOST=0.0.0.0. Vedi Variabili di aggiornamento del token
  • Vedi Autenticazione per tutti i passi di risoluzione dei problemi OAuth

Ottenere aiuto

Se incontri problemi non coperti in questa sezione di risoluzione dei problemi:

  1. Controlla la console/silog dell'utente sviluppatore del tuo client MCP per messaggi di errore dettagliati (ad esempio, la Console Sviluppatore di VS Code, gli Strumenti per sviluppatori di Cursor o l'output di --debug di Claude Code)
  2. Controlla i log del server — i log del container Docker, o i log del client MCP quando usi la distribuzione npm
  3. Contatta il nostro team di supporto a helpdesk@deque.com con:
    • Il tuo client MCP e la sua versione
    • La tua versione di Docker (distribuzione Docker) o la versione di Node.js (distribuzione npm)
    • Messaggi di errore completi
    • Passaggi per riprodurre il problema

Is this page helpful?

Help us improve this page

Still need help?