Risoluzione dei problemi

Questa pagina copre i problemi comuni sia della distribuzione Docker che npm. I problemi che si applicano solo a una distribuzione sono etichettati di conseguenza.

Il server non si avvia

• Assicurarsi che Docker sia in esecuzione (distribuzione Docker), o che Chromium sia installato (distribuzione npm — vedere installazione di Chromium)
• Verificare che le credenziali siano corrette: o il vostro AXE_API_KEY o il vostro AXE_ACCESS_TOKEN, ma non entrambi (il server non si avvia se entrambi sono impostati)
• Verificare di avere accesso al server axe MCP (contattare il supporto se necessario)

Timeout durante la scansione

• Aumenta BROWSER_TIMEOUT_MS per pagine complesse
• Assicurarsi che l'URL di destinazione sia accessibile dalla rete
• Controllare eventuali problemi di connettività di rete

Il server di sviluppo locale non riesce a effettuare la scansione con ERR_CONNECTION_REFUSED

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

Se lo strumento analyze fallisce con un net::ERR_CONNECTION_REFUSED errore durante il tentativo di scansione di un server di sviluppo locale in esecuzione, ciò è probabilmente dovuto al fatto che il server axe MCP viene eseguito all'interno di un contenitore Docker e non può raggiungere servizi vincolati solo a localhost (cioè, 127.0.0.1) sulla vostra macchina host.

Esempio di errore:

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

Soluzione: Avviare il server di sviluppo con il flag --host impostato su 0.0.0.0 in modo che ascolti su tutte le interfacce di rete, rendendolo raggiungibile all'interno del contenitore Docker:

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

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

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 disponga di memoria sufficiente 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 di Docker non hanno bisogno di installare Chromium e non sono affetti dagli errori descritti qui.

Cosa significa l'errore

Il server axe MCP esegue le scansioni di accessibilità guidando un vero browser tramite Playwright. Con la distribuzione npm, quel browser — Chromium — deve essere installato sul vostro 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 si avvia (o fallisce alla prima scansione) con un errore che indica che Chromium non ha potuto essere avviato.

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

Soluzione standard

Installare la revisione di Chromium che corrisponde alla versione di Playwright fornita dal server axe MCP — attualmente 1.60.0. Fissa Playwright a quella versione in modo che un semplice npx playwright non si risolva in una versione più recente con una revisione di Chromium che il server non supporta:

npx playwright@1.60.0 install chromium

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

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@1.60.0 install-deps chromium

Puoi anche combinare entrambi i passaggi in un unico comando:

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

Usa un browser che hai già

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

Perché Chromium non è incluso

Playwright fissa una 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 le sue dimensioni, lo legherebbe al binario di una piattaforma e diventerebbe obsoleto non appena Playwright aggiorna la sua revisione fissa. 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 singolo e noto.)

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

L'aggiornamento axe-mcp-server può includere una versione più recente di Playwright, che può fissare una revisione più recente di Chromium rispetto a quella attualmente installata. Quando ciò accade, potresti vedere di nuovo lo stesso errore di avvio dopo un aggiornamento. La soluzione è la stessa: riesegui l'installazione con la versione di Playwright fornita dal server aggiornato in modo che Chromium corrisponda:

npx playwright@1.60.0 install chromium

Come regola generale, riesegui questo comando — utilizzando la versione di Playwright fornita dall'attuale versione — ogni volta che aggiorni axe-mcp-server e il server segnala una discrepanza di Chromium all'avvio.

Errori di autenticazione

Chiave API

• Verifica che la tua chiave API sia valida e non sia scaduta
• Assicurati che il tuo abbonamento al 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 è impostato — se AXE_ACCESS_TOKEN è impostato anche, il server fallirà all'avvio
• Conferma che l'URL del server axe sia corretto — se la tua organizzazione utilizza un'istanza regionale, cloud privata o on-premises di axe, AXE_SERVER_URL deve essere impostato sull'URL di base della tua istanza. Vedi Riferimento alla Configurazione per i dettagli.

OAuth

• Conferma che solo AXE_ACCESS_TOKEN è impostato — se AXE_API_KEY è impostato anche, il server fallirà all'avvio
• Esegui npx @deque/axe-auth token nel tuo terminale per confermare che hai un token valido; se si conclude con un codice diverso da zero, riautenticati con npx @deque/axe-auth login
• Conferma che l'URL del server axe sia corretto
• Se il tuo token è scaduto a metà sessione, riavvia la connessione al server MCP nel tuo client (ad esempio, riavviando Claude Code, attivando e disattivando il server nelle impostazioni MCP di Cursor, o cliccando direttamente il pulsante CodiceLens "Riavvia" sopra l'entrata axe MCP Server in mcp.json) per ottenere un token nuovo
• Vedi Autenticazione per tutti i passaggi di risoluzione dei problemi OAuth

Ottenere aiuto

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

1. Controlla la Console Sviluppatori di VS Code per messaggi di errore dettagliati
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:
   • La tua versione di VS Code
   • La tua versione di Docker (distribuzione Docker) o la versione di Node.js (distribuzione npm)
   • Messaggi di errore completi
   • Passaggi per riprodurre il problema