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 riprova una richiesta e sospende un motore che non risponde

SearXNG non continua a inviare richieste a un motore che le rifiuta. Un motore che presenta errori viene sospeso. Durante la sospensione viene completamente ignorato. Per questo un motore non funzionante può risultare semplicemente assente.

Due livelli controllano questo comportamento. Entrambi si trovano sotto search: in settings.yml. Prima di incollare qualsiasi configurazione, verifica i nomi e i valori di queste chiavi in searx/settings.yml per la versione effettivamente in esecuzione. Questi parametri sono cambiati tra le varie release. Inoltre, l'esempio nella pagina della documentazione delle impostazioni mostra ancora sospensioni più lunghe rispetto a quelle del file che SearXNG carica realmente. Nella versione distribuita in searx/settings.yml il 17 ottobre 2026, i valori predefiniti sono:

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

Il primo livello gestisce gli errori ordinari, come un timeout. Il ban 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. La maggior parte di questi valori è molto più alta. 180 secondi corrispondono a tre minuti, per un rifiuto semplice o un errore 429. 3600 corrisponde a un'ora, per una CAPTCHA generica. 86400 corrisponde a un giorno intero. 604800 corrisponde a una settimana. 1296000 corrisponde a quindici giorni. Le chiavi con prefisso cf_ si applicano quando la challenge viene riconosciuta come una challenge Cloudflare. Quelle con prefisso recaptcha_ si applicano quando viene riconosciuta come reCAPTCHA.

Questo spiega il sintomo che fa perdere più tempo. Individui la causa, la correggi, ma il motore continua a non restituire risultati per un'ora o, dopo una challenge Cloudflare, per diversi giorni. Il motore è ancora sospeso. La sospensione viene mantenuta dal processo in esecuzione. Riavviando il container la si cancella e la ricerca successiva prova di nuovo a usare il motore. In questo caso è sufficiente un semplice riavvio. Prima di ricreare inutilmente le immagini, conviene sapere quando è sufficiente un riavvio e quando è necessario ricreare il container. Se il motore presenta nuovamente errori subito dopo il riavvio, la correzione non ha funzionato.

Un'impostazione per singolo motore richiede particolare attenzione. retry_on_http_error riprova una richiesta quando il motore risponde con i codici di stato specificati. Se un motore ti sta bloccando, i nuovi tentativi 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 17 ottobre 2026, la documentazione amministrativa di SearXNG risolve questo problema con un tunnel manuale. Si apre un proxy SOCKS attraverso il server, si configura il browser desktop per utilizzarlo e si completa manualmente la verifica, mentre il motore vede 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 attraverso la connessione SSH. -N non esegue alcun comando remoto e -q mantiene l'output silenzioso, quindi un tunnel funzionante non stampa nulla e non termina. 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, mentre il secondo dovrebbe stampare l'indirizzo 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, caricare nello stesso browser il verificatore dell'indirizzo per confermare che riporti il server e visitare il motore che sta eseguendo la verifica. Completare lì la verifica.

È importante considerare anche i limiti di questo metodo. Il cookie fornito 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. Questa registrazione scade secondo una pianificazione stabilita dal motore e non pubblicata. La procedura non è automatizzata, quindi 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. Non basare un'istanza 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.

Correzione duratura: inviare le richieste in uscita tramite un proxy

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

outgoing:
  request_timeout: 3.0
  extra_proxy_timeout: 10
  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 indica che il nome viene inviato al proxy invece di essere risolto sul server. Aumenta contemporaneamente il timeout disponibile. request_timeout ha un valore predefinito di 3.0 secondi; un proxy aggiunge un round trip a ogni richiesta e i motori che prima rispondevano in tempo iniziano invece a fallire per timeout. extra_proxy_timeout esiste proprio per questo caso e aggiunge secondi quando viene usato un proxy. Impostalo come numero intero, ad esempio 10. A differenza di request_timeout, che accetta valori decimali, extra_proxy_timeout è un intero nello schema delle impostazioni. Di conseguenza, un valore come 10.0 viene rifiutato come settings.yml non valido, anche se l'esempio commentato nella pagina della documentazione delle impostazioni per le richieste in uscita lo riporta in quel formato.

Costi dell'uso di un proxy:

• L'operatore del proxy vede quali motori interroga la tua istanza e quando. TLS (Transport Layer Security) mantiene i termini di ricerca fuori dai suoi log, perché la query è contenuta nella richiesta crittografata, ma l'andamento e la temporizzazione del tuo traffico restano visibili.
• Un indirizzo di uscita condiviso è condiviso con tutti gli altri utenti che lo pagano. Se eseguono scraping, ne erediti la reputazione, a volte più rapidamente del blocco che stavi cercando di evitare.
• Le pool di proxy residenziali economiche sono spesso composte da dispositivi di privati i cui proprietari non hanno accettato consapevolmente di trasportare traffico. Verifica esattamente 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 alle reti dei datacenter spesso applica controlli almeno altrettanto rigidi ai nodi di uscita.
• Le ricerche ora dipendono da un servizio esterno al tuo server. Il servizio può smettere di funzionare secondo tempistiche proprie e rendere indisponibili anche i tuoi risultati.

Un proxy sposta il blocco invece di rimuoverlo e la valutazione della privacy della tua istanza ora include anche una terza parte. Se il motivo per cui esegui il self-hosting è mantenere una gestione semplice della privacy, valuta questo aspetto rispetto a cosa nasconde davvero un'istanza self-hosted e cosa invece non nasconde prima di registrarti a un servizio.

Soluzione duratura: eseguire intenzionalmente un insieme più ridotto di motori

L’opzione che molti trascurano è accettare un numero inferiore di motori. Il valore di SearXNG sta nell’unione dei risultati, e l’unione di sei motori che rispondono sempre è preferibile a venti motori, metà dei quali rimane sospesa per ore o giorni consecutivi. Monitora /stats per una settimana e mantieni i motori che dal tuo indirizzo mostrano un funzionamento regolare.

I motori ai quali accedi con una API key si comportano in modo diverso, perché il motore sa chi sei e applica una quota invece di tentare di determinare se sei una persona. Il compromesso consiste nella gestione di un account, nella presenza di una chiave nel file delle impostazioni e, in genere, in un costo. Per uno o due motori che utilizzi realmente, questa è spesso la soluzione meno problematica.

Valuta questa scelta considerando anche gli altri strumenti. Un motore sospeso non è visibile a tutto ciò che legge i risultati tramite API, perché l’API JSON interrogata da Open WebUI e strumenti simili restituisce semplicemente meno risultati, invece di un errore rilevabile dallo strumento. Se un processo automatizzato dipende dalla tua istanza, interroga /stats/errors a intervalli pianificati 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 non restituisce ancora risultati dopo la correzione del problema?

Perché è ancora sospeso. Quando SearXNG rileva una challenge o un rifiuto da parte di un motore, smette di interrogarlo per il periodo impostato in search.suspended_times. I valori predefiniti forniti vanno da tre minuti a quindici giorni, a seconda del tipo di rifiuto. La sospensione è mantenuta dal processo in esecuzione. Il riavvio del container la annulla e la ricerca successiva prova nuovamente a usare il motore. Se il motore fallisce di nuovo subito dopo il riavvio, la correzione non ha risolto il problema.

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

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

Una VPN o un proxy sul server possono risolvere i CAPTCHA dei motori?

A volte sì, ma comportano dei costi. L'instradamento delle richieste in uscita tramite outgoing.proxies modifica l'indirizzo visto dal motore. Questo 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 un intervento diretto da parte tua sulla challenge. Qualsiasi soluzione automatizzata per rispondere alle challenge contrasta con le regole dichiarate dal motore e smette di funzionare ogni volta che la challenge cambia. In questo modo dovresti gestire uno scraper invece di eseguire un'istanza di ricerca. La soluzione più stabile consiste nel rimuovere i motori che bloccano il tuo indirizzo.