Come risolvere gli errori CAPTCHA in SearXNG

Che cosa significa un errore CAPTCHA di SearXNG

Gli errori CAPTCHA di SearXNG provengono dai motori che la tua istanza interroga. Il server ha richiesto risultati a un motore, ma il motore ha risposto con una pagina di verifica invece dei risultati. SearXNG ha quindi registrato un errore per quel motore perché nella risposta non c'era nulla da analizzare. La tua istanza funziona correttamente. Un sistema che non controlli ha stabilito che la richiesta non sembrava provenire da una persona.

Questo fatto determina tutte le correzioni descritte di seguito. La decisione viene presa sull'hardware del motore, quindi nulla nella tua settings.yml può modificarla. Puoi cambiare l'indirizzo da cui parte la richiesta, i motori che interroghi e il comportamento dell'istanza quando un motore inizia a rifiutare le richieste.

Due problemi che possono sembrare identici e come distinguerli

Il primo problema si verifica quando la tua istanza risponde HTTP 429 (troppe richieste) al tuo browser. Si tratta del limitatore di SearXNG, il livello di rilevamento dei bot che si trova davanti all'endpoint di ricerca. Viene eseguito sul tuo server e puoi configurarlo direttamente. il limitatore che restituisce 429 ai tuoi utenti è un problema distinto, con impostazioni diverse; nessuna delle indicazioni riportate di seguito si applica a quel caso.

Il secondo problema si verifica a monte. La pagina dei risultati viene caricata normalmente, ma uno o più motori non compaiono nei risultati oppure mostrano un avviso di errore. La tua istanza non ha rifiutato alcuna richiesta. È un motore ad avere rifiutato il tuo server.

• La pagina non viene caricata oppure l'endpoint di ricerca risponde 429: controlla il limitatore.
• La pagina viene caricata, ma i risultati sono pochi oppure un motore è contrassegnato da un errore: controlla i servizi a monte e continua a leggere.

Entrambi i problemi possono verificarsi sulla stessa istanza e possono influenzarsi a vicenda, perché un limitatore configurato in modo troppo permissivo consente il passaggio di traffico che aumenta la frequenza delle query in uscita. Diagnosticali uno alla volta.

Perché i motori di SearXNG restituiscono errori CAPTCHA su un VPS ma non sul mio laptop?

Dipende dall'indirizzo da cui proviene la richiesta. La connessione domestica usa un indirizzo appartenente all'intervallo di un ISP consumer (internet service provider), condiviso nel tempo da molte persone. Il VPS usa invece un indirizzo appartenente a un intervallo di un datacentre. Questi intervalli sono pubblici: chiunque può verificare quali indirizzi appartengono a un hosting provider. Un motore che vuole bloccare gli scraper inizia quindi a considerare sospette le richieste provenienti dagli intervalli degli hosting provider, perché in questi intervalli solo una piccola parte del traffico proviene da persone che usano un browser.

All'indirizzo si aggiungono altri fattori. La tua istanza invia una richiesta per ogni motore a ogni ricerca dell'utente. Di conseguenza, anche pochi utenti generano da un singolo indirizzo una frequenza di richieste che nessuna singola persona produrrebbe. Per progettazione, SearXNG non mantiene una sessione con il motore e non invia cookie persistenti. Ogni richiesta arriva quindi senza uno storico associato. Inoltre, l'indirizzo può avere una reputazione che non hai creato tu, perché i provider riutilizzano gli indirizzi e il precedente assegnatario potrebbe aver eseguito scraping da quell'indirizzo per mesi.

Il rifiuto non è sempre evidente. Un motore può rispondere con 403, con 429 oppure con HTTP 200 e una pagina di challenge nel corpo della risposta. Quest'ultimo caso crea confusione: il controllo del codice di stato indica che il motore funziona, mentre SearXNG non trova risultati nella risposta. Per questo devi leggere il report degli errori della tua istanza, invece di usare curl sul motore e controllare la riga dello stato HTTP.

Leggi ciò che segnala la tua istanza prima di modificare qualsiasi impostazione

Ogni correzione riportata di seguito parte dal nome del motore che sta generando l'errore e dal motivo registrato dalla tua istanza. SearXNG espone entrambe le informazioni. La pagina /stats elenca i motori con il numero di errori e l'affidabilità; /stats/errors restituisce i dettagli dell'errore in formato JSON, più semplici da conservare e confrontare la settimana successiva. Aprili nel browser che usi normalmente per l'istanza.

Il log del container registra gli stessi eventi mentre si verificano. Il nome del servizio indicato qui è quello usato nel file compose pubblicato con la documentazione del container; usa il tuo se è diverso.

docker compose logs -f core

Esegui una ricerca che genera un errore mentre monitori il log. Dovresti vedere comparire una voce relativa al motore che genera l'errore mentre la ricerca è in corso. Annota il nome del motore e la stringa esatta del motivo stampata dalla tua istanza. Non copiare il nome di un motore da un post, incluso questo. L'insieme dei motori che limitano gli indirizzi dei datacenter cambia di mese in mese e il motore che genera errori nella tua istanza potrebbe funzionare perfettamente per chi ha scritto il post che stai leggendo.

Se la pagina dei risultati non mostra alcun errore, ma i risultati sono pochi, controlla display_error_messages per quel motore. Per impostazione predefinita è true; un'istanza in cui questa opzione è stata disattivata nasconde proprio il messaggio che ti serve.

Come SearXNG ritenta le richieste e sospende un motore che non risponde

SearXNG non continua a inviare richieste a un motore che le rifiuta. Un motore che genera errori viene sospeso e, finché resta sospeso, viene completamente escluso. In questo modo un motore non funzionante diventa un motore semplicemente assente dai risultati.

Il comportamento è controllato da due livelli, entrambi presenti in search: all'interno di settings.yml. Prima di incollare qualsiasi valore, verifica questi nomi nella documentazione delle impostazioni relativa alla versione effettivamente in uso, perché sono cambiati tra le varie release. Come documentato il 2 settembre 2026, i valori predefiniti sono:

search:
  ban_time_on_fail: 5
  max_ban_time_on_fail: 120
  suspended_times:
    SearxEngineAccessDenied: 86400
    SearxEngineCaptcha: 86400
    SearxEngineTooManyRequests: 3600
    cf_SearxEngineCaptcha: 1296000
    cf_SearxEngineAccessDenied: 86400
    recaptcha_SearxEngineCaptcha: 604800

Il primo livello gestisce gli errori ordinari, come un timeout. Il blocco inizia dopo ban_time_on_fail secondi e aumenta a ogni errore consecutivo, fino a max_ban_time_on_fail. Per impostazione predefinita, il limite è di due minuti. Un motore instabile torna quindi disponibile automaticamente entro pochi minuti dalla risoluzione del problema.

Il secondo livello gestisce gli errori descritti in questa guida. Quando SearXNG riconosce la risposta come una challenge o un rifiuto, invece che come un errore generico, applica la voce corrispondente di suspended_times. Questi valori sono molto più elevati. 86400 secondi corrispondono a un giorno intero. 604800 corrisponde a una settimana. 1296000 corrisponde a quindici giorni. Le chiavi con prefisso cf_ vengono applicate quando la challenge viene riconosciuta come proveniente da Cloudflare. recaptcha_ viene applicato quando viene riconosciuta come reCAPTCHA.

Questo spiega il sintomo che fa perdere più tempo. Individui la causa, la risolve e il motore continua a non restituire risultati per ore. È ancora sospeso. La sospensione viene mantenuta dal processo in esecuzione. Riavviando il container si cancella lo stato e la ricerca successiva prova nuovamente a usare il motore. In questo caso è sufficiente un normale riavvio. Prima di ricreare immagini senza motivo, conviene sapere quando è sufficiente un riavvio e quando è necessario ricreare il container. Se il motore fallisce di nuovo subito dopo il riavvio, la correzione non ha risolto il problema.

Una specifica per singolo motore richiede particolare attenzione. retry_on_http_error ritenta una richiesta quando il motore risponde con i codici di stato indicati. Se un motore sta bloccando il server, i tentativi aggiuntivi generano altro traffico verso il sistema che ha già classificato il server come bot. Lascia questa impostazione invariata, a meno che tu non stia gestendo un motore realmente intermittente.

Documentazione del tunnel SSH upstream e ciò che non risolve

Verificata il 2 settembre 2026, la documentazione amministrativa di SearXNG risolve questo problema con un tunnel manuale. Si apre un proxy SOCKS tramite il server, si configura il browser desktop per usarlo e si completa manualmente la verifica mentre il motore rileva l'indirizzo del server.

ssh -q -N -D 8080 user@example.org

-D 8080 apre un server SOCKS locale sulla porta 8080 e inoltra il traffico tramite la connessione SSH. -N non esegue alcun comando remoto e -q mantiene l'output silenzioso, quindi un tunnel funzionante non stampa nulla e non restituisce il prompt. Verificarlo da un secondo terminale:

curl -x socks://127.0.0.1:8080 http://ipecho.net/plain
curl http://ipecho.net/plain

Il primo comando dovrebbe stampare l'indirizzo del server e il secondo quello del desktop. Se i due risultati sono identici, la richiesta non passa attraverso il tunnel. Configurare quindi le impostazioni di rete del browser con un proxy SOCKS5 all'indirizzo 127.0.0.1 sulla porta 8080, aprire lo stesso servizio di verifica dell'indirizzo nel browser per confermare che riporti l'indirizzo del server e visitare il motore che sta richiedendo la verifica. Completare la verifica dal browser.

Occorre però considerare quattro limiti di questo metodo. Il cookie rilasciato dal motore viene salvato nel browser desktop e SearXNG non può accedere ai cookie del browser. L'unico elemento che può aiutare l'istanza è quindi ciò che il motore registra associato all'indirizzo stesso. Questo dato scade secondo una pianificazione scelta dal motore e non pubblicata. La procedura non è automatizzata, quindi la volta successiva sarà necessario ripeterla manualmente. Inoltre, se l'istanza è utilizzata da altre persone, il volume di query che ha attivato la verifica continua a essere generato e la verifica ricompare.

Usarlo per rendere operativa un'istanza oggi stesso. Non progettare un'istanza basandosi su questo metodo.

Soluzione duratura: rimuovere o ripesare i motori che causano problemi

La soluzione duratura più economica consiste nel non interrogare un motore che non può servire il tuo server. Il tuo settings.yml inizia con use_default_settings: true nell'immagine del container. Questo significa che una voce sotto engines: con un name corrispondente sostituisce soltanto le chiavi elencate e lascia invariato il resto della definizione predefinita.

use_default_settings: true

engines:
  - name: <engine name from your stats page>
    disabled: true
  - name: <another engine name>
    weight: 0.3

disabled: true disattiva il motore per impostazione predefinita, ma lo mantiene nella pagina delle preferenze. Un utente che vuole utilizzarlo può quindi riattivarlo per le proprie ricerche. inactive: true lo rimuove completamente dalle impostazioni dell'utente. È l'opzione corretta per un motore che non funzionerà mai dal tuo indirizzo. weight svolge una funzione diversa: modifica il peso dei risultati del motore quando SearXNG li aggrega e li ordina. Un peso inferiore a 1 consente di mantenere un motore marginale senza permettergli di occupare le prime posizioni.

Dopo la modifica, riavvia il container ed esegui alcune ricerche. Controlla quindi di nuovo /stats. Una pagina delle statistiche pulita, con sei motori funzionanti, è più utile di una pagina piena di errori con venti motori.

Una correzione duratura: inviare le richieste in uscita tramite un proxy

SearXNG può inviare tramite un proxy le richieste in uscita ai motori, modificando l'indirizzo che il motore rileva. Impostalo globalmente in outgoing: oppure per un singolo motore quando il problema riguarda soltanto quel motore.

outgoing:
  request_timeout: 2.0
  extra_proxy_timeout: 10.0
  proxies:
    all://:
      - socks5h://user:password@proxy:1080

engines:
  - name: <engine name>
    proxies:
      http: socks5h://user:password@proxy:1080
      https: socks5h://user:password@proxy:1080

Preferisci socks5h:// a socks5:// quando vuoi che sia il proxy a risolvere il nome host, perché h fa sì che il nome venga inviato al proxy invece di essere risolto sul server. Aumenta contemporaneamente il timeout. request_timeout ha un valore predefinito di 2.0 secondi; il proxy aggiunge un round trip a ogni richiesta e i motori che prima rispondevano entro il limite iniziano invece a fallire per timeout. extra_proxy_timeout esiste proprio per questo caso e aggiunge secondi quando viene utilizzato un proxy.

Costi dell'uso di un proxy:

• Il gestore del proxy vede quali motori interroga la tua istanza e quando. TLS (transport layer security) impedisce che i termini di ricerca finiscano nei suoi log, perché la query è contenuta nella richiesta cifrata, ma può comunque leggere la struttura e la temporizzazione del tuo traffico.
• Un indirizzo di uscita condiviso è condiviso con tutti gli altri utenti che lo utilizzano. Se eseguono attività di scraping, ne erediti la reputazione, talvolta prima ancora che il blocco che stavi evitando venga applicato.
• I pool di proxy residenziali economici sono spesso composti da dispositivi di utenti che non hanno accettato consapevolmente di trasportare traffico. Verifica che cosa stai acquistando.
• using_tor_proxy: true instrada il traffico tramite Tor, ma gli indirizzi dei nodi di uscita sono pubblicati integralmente e un motore che applica controlli agli intervalli dei datacenter di solito applica controlli almeno altrettanto severi ai nodi di uscita.
• Le ricerche ora dipendono da un servizio esterno al server, che può avere problemi secondo i propri tempi e interrompere di conseguenza anche i risultati.

Un proxy sposta il blocco invece di rimuoverlo e la valutazione della privacy della tua istanza ora include una terza parte. Se la privacy limitata è il motivo per cui usi il self-hosting, confrontala con ciò che un'istanza self-hosted nasconde davvero e ciò che non nasconde prima di registrarti a qualsiasi servizio.

Una soluzione duratura: esegui intenzionalmente un set più piccolo di motori

L’opzione che più spesso viene ignorata consiste nell’accettare un numero inferiore di motori. Il valore di SearXNG sta nell’unione dei risultati, e un’unione di sei motori che rispondono sempre è migliore di una configurazione con venti motori, metà dei quali rimane sospesa per un’intera giornata. Monitora /stats per una settimana e mantieni i motori che registrano un comportamento regolare dal tuo indirizzo.

I motori ai quali accedi con una chiave API si comportano in modo diverso, perché il motore sa chi sei e applica una quota invece di cercare di stabilire se sei una persona. Il compromesso consiste nell’avere un account, una chiave memorizzata nel file delle impostazioni e, di norma, un costo. Per uno o due motori che utilizzi davvero, questa è spesso la soluzione meno problematica.

Valuta questa scelta anche in base agli altri strumenti che utilizzi. Un motore sospeso non è visibile a nessuno strumento che legge i risultati tramite API, perché l’API JSON che Open WebUI e strumenti simili interrogano restituisce semplicemente meno risultati, senza produrre un errore rilevabile dallo strumento. Se un processo automatizzato dipende dalla tua istanza, interroga /stats/errors a intervalli prestabiliti invece di aspettare che qualcuno segnali un peggioramento dei risultati.

Vale la pena insistere?

Per rispondere, conta gli utenti. Un'istanza usata da una sola persona invia poche ricerche al giorno dallo stesso indirizzo, un ritmo che molti motori non contestano mai. Quando uno di questi presenta una challenge, la soluzione è semplice: rimuovi il motore e noterai appena la sua assenza. Questa è l'esperienza normale di eseguire SearXNG per uso personale su un piccolo VPS e non richiede né tunnel né proxy.

Un'istanza pubblica o condivisa è una macchina diversa che esegue lo stesso software. Il fattore determinante è la frequenza delle query, che aumenta con ogni utente aggiunto; di conseguenza, le challenge arrivano più rapidamente di quanto qualsiasi configurazione possa gestire. Pianifica fin dall'inizio un insieme più ristretto di motori e ricorda che qualsiasi proxy aggiunto ora trasporta le ricerche di altre persone usando il tuo account.

I client automatizzati si collocano a metà strada, ma tendono verso lo scenario più difficile. Un agente che esegue diverse ricerche per rispondere a una domanda genera picchi che nessun utente umano produce. Per questo, un'istanza a cui indirizzi agenti di programmazione e strumenti di ricerca riceve le challenge prima della stessa istanza usata manualmente. In questo caso, scegli i motori in base all'affidabilità e non all'ampiezza della copertura. Lascia che l'agente lavori con risultati che può effettivamente ottenere.

La regola generale è questa: insisti con un motore quando è il motivo per cui esegui il servizio autonomamente e rimuovilo quando non lo è.

FAQ

Perché un motore SearXNG continua a non restituire risultati dopo che ho risolto il problema?

Perché è ancora sospeso. Quando SearXNG rileva una challenge o un rifiuto da parte di un motore, interrompe le interrogazioni verso quel motore per il periodo impostato in search.suspended_times. In base al tipo di rifiuto, i valori predefiniti vanno da un'ora a quindici giorni. La sospensione viene mantenuta dal processo in esecuzione. Il riavvio del container la cancella e la ricerca successiva prova nuovamente a usare il motore. Se il motore fallisce di nuovo subito dopo il riavvio, la correzione non ha funzionato.

Un errore CAPTCHA di un motore è uguale al 429 restituito dalla mia istanza?

No. I due errori viaggiano in direzioni opposte. Un 429 dalla tua istanza al browser indica che il limitatore integrato in SearXNG ha stabilito che la richiesta sembrava automatizzata. Questo limite è configurabile da te. Un errore CAPTCHA o di blocco indica invece che un motore upstream sta rifiutando il tuo server. La decisione viene presa su infrastruttura che non controlli. Se la pagina dei risultati viene caricata e mancano soltanto alcuni motori, si tratta del secondo caso.

Una VPN o un proxy sul mio server risolveranno i CAPTCHA dei motori?

A volte, ma con alcuni costi. Instradare le richieste in uscita tramite outgoing.proxies modifica l'indirizzo visto dal motore e può rimuovere un blocco associato all'intervallo di indirizzi del tuo datacenter. Il gestore del proxy può quindi vedere quali motori interroghi e quando. Inoltre, un indirizzo di uscita condiviso può avere una reputazione negativa dovuta ad altri clienti. La latenza aggiuntiva può causare timeout, a meno che tu non aumenti request_timeout e extra_proxy_timeout. Tor è disponibile tramite using_tor_proxy, ma gli indirizzi di uscita sono pubblici e sottoposti frequentemente a challenge.

Posso configurare SearXNG per risolvere automaticamente il CAPTCHA?

Non esiste un'impostazione per farlo. Il metodo documentato dal progetto è manuale: un tunnel SSH SOCKS, il tuo browser e il tuo intervento diretto sulla challenge. Qualsiasi soluzione che costruisci per rispondere automaticamente alle challenge opera in contrasto con la policy dichiarata dal motore e smette di funzionare ogni volta che la challenge cambia. In questo modo finisci per mantenere uno scraper invece di gestire un'istanza di ricerca. La soluzione più stabile è rimuovere i motori che bloccano il tuo indirizzo.