Corriger les erreurs CAPTCHA des moteurs dans SearXNG

Ce que signifie une erreur CAPTCHA de SearXNG

Les erreurs CAPTCHA de SearXNG proviennent des moteurs interrogés par votre instance. Votre serveur a demandé des résultats à un moteur, mais celui-ci a renvoyé une page de challenge au lieu des résultats. SearXNG a donc enregistré une erreur pour ce moteur, car la réponse ne contenait rien qu’il puisse analyser. Votre instance fonctionne correctement. Une machine que vous ne contrôlez pas a simplement considéré que votre requête ne ressemblait pas à une requête humaine.

Ce point détermine toutes les corrections présentées ci-dessous. La décision a été prise sur l’infrastructure du moteur. Aucun réglage de votre settings.yml ne peut donc la contourner. En revanche, vous pouvez modifier l’adresse depuis laquelle la requête est envoyée, les moteurs que vous interrogez, ainsi que le comportement de votre instance lorsqu’un moteur commence à refuser les requêtes.

Deux pannes qui se ressemblent, et comment les distinguer

La première panne survient lorsque votre propre instance renvoie une réponse HTTP 429 (trop de requêtes) à votre navigateur. Il s’agit du limiteur de SearXNG, la couche de détection des bots placée devant le point d’accès de recherche. Elle s’exécute sur votre serveur et vous pouvez la configurer. Le limiteur qui renvoie 429 à vos propres utilisateurs est un problème distinct, avec des paramètres différents. Aucun des conseils ci-dessous ne s’y applique.

La seconde panne se situe en amont. La page de résultats se charge normalement, mais un ou plusieurs moteurs sont absents des résultats ou affichent un message d’erreur. Rien sur votre instance n’a refusé la requête. Un moteur a refusé votre serveur.

• La page ne se charge pas ou le point d’accès de recherche renvoie 429 : vérifiez votre limiteur.
• La page se charge, mais les résultats sont peu nombreux, ou un moteur est signalé en erreur : examinez le problème en amont et poursuivez la lecture.

Les deux pannes peuvent survenir sur la même instance et s’alimenter mutuellement, car un limiteur trop permissif laisse passer un trafic qui augmente votre débit de requêtes sortantes. Diagnostiquez-les séparément.

Pourquoi les moteurs SearXNG renvoient-ils des erreurs CAPTCHA sur un VPS, mais pas sur mon ordinateur portable ?

Cela dépend de l’adresse depuis laquelle la requête est envoyée. Votre connexion personnelle utilise une adresse appartenant à une plage d’un FAI grand public (fournisseur d’accès à Internet), partagée au fil du temps par de nombreuses personnes. Votre VPS utilise une adresse appartenant à une plage de datacenter. Ces plages sont publiées : n’importe qui peut vérifier quelles adresses appartiennent à un hébergeur. Un moteur qui veut empêcher les scrapers d’accéder à son service commence donc par considérer les requêtes provenant de plages d’hébergement comme suspectes, car ces plages contiennent très peu d’utilisateurs humains derrière un navigateur.

D’autres facteurs s’ajoutent à l’adresse. Votre instance envoie une requête par moteur et par recherche utilisateur. Même un petit nombre d’utilisateurs peut donc produire, depuis une seule adresse, un débit qu’une seule personne ne génère jamais. SearXNG ne conserve aucune session avec le moteur et n’envoie pas de cookie persistant, par conception. Chaque requête arrive donc sans historique associé. De plus, l’adresse peut avoir un historique que vous n’avez pas créé, car les fournisseurs recyclent leurs adresses et l’ancien locataire a peut-être effectué du scraping depuis cette adresse pendant des mois.

Le refus n’est pas toujours un échec évident. Un moteur peut répondre avec le code 403, avec le code 429, ou avec le code HTTP 200 et une page de challenge dans le corps de la réponse. Ce dernier cas prête à confusion : la vérification du code d’état indique que le moteur fonctionne, tandis que SearXNG ne trouve aucun résultat dans la réponse. C’est pourquoi vous devez consulter le rapport d’erreurs de votre propre instance, au lieu d’utiliser curl sur le moteur et de regarder la ligne d’état.

Consultez ce que votre instance signale avant de modifier quoi que ce soit

Chaque correctif ci-dessous commence par le nom du moteur en échec et par la raison que votre instance a enregistrée. SearXNG expose ces deux informations. La page /stats répertorie les moteurs avec leur nombre d’erreurs et leur fiabilité. /stats/errors renvoie le détail de l’erreur au format JSON, ce qui facilite sa conservation et sa comparaison la semaine suivante. Ouvrez ces pages dans le navigateur que vous utilisez habituellement pour l’instance.

Le journal du conteneur contient les mêmes événements au moment où ils se produisent. Le nom du service indiqué ici est celui utilisé dans le fichier compose fourni avec la documentation du conteneur. Utilisez le vôtre s’il est différent.

docker compose logs -f core

Lancez une recherche qui échoue pendant que le journal est suivi. Une entrée correspondant au moteur en échec devrait apparaître pendant l’exécution de la recherche. Notez le nom du moteur et la chaîne de raison exacte affichée par votre instance. Ne copiez pas le nom d’un moteur depuis un article de blog, y compris celui-ci. L’ensemble des moteurs qui bloquent les adresses de datacenters change d’un mois à l’autre. Le moteur qui échoue chez vous peut fonctionner parfaitement pour l’auteur de l’article que vous lisez.

Si la page de résultats n’affiche aucune erreur, mais que les résultats sont peu nombreux, vérifiez display_error_messages pour ce moteur. Cette option vaut true par défaut. Une instance sur laquelle elle a été désactivée masque le seul message dont vous avez besoin.

Comment SearXNG réessaie une requête et suspend un moteur défaillant

SearXNG ne bombarde pas indéfiniment un moteur qui refuse ses requêtes. Un moteur défaillant est suspendu. Tant qu’il reste suspendu, il est entièrement ignoré. C’est ainsi qu’un moteur défectueux devient un moteur silencieusement absent.

Deux niveaux contrôlent ce comportement. Ils se trouvent tous les deux sous search: dans settings.yml. Vérifiez ces noms de clés et leurs valeurs dans searx/settings.yml pour la version que vous utilisez avant de coller quoi que ce soit. Ils ont changé entre les releases. De plus, l’exemple de la page de documentation des paramètres indique encore des suspensions plus longues que celles réellement chargées par SearXNG. Dans la version fournie dans searx/settings.yml le 17 October 2026, les valeurs par défaut sont les suivantes :

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

Le premier niveau gère les échecs ordinaires, comme un timeout. Le bannissement commence après ban_time_on_fail secondes et augmente à chaque échec consécutif, jusqu’à max_ban_time_on_fail. Par défaut, la limite est de deux minutes. Un moteur instable reprend donc automatiquement son fonctionnement dans les minutes qui suivent la résolution du problème.

Le second niveau gère les échecs concernés par ce guide. Lorsque SearXNG identifie la réponse comme un challenge ou un refus, plutôt que comme une erreur générique, il applique l’entrée correspondante de suspended_times. La plupart de ces valeurs sont beaucoup plus élevées. 180 secondes correspondent à trois minutes, pour un refus simple ou une réponse 429. 3600 correspondent à une heure, pour un CAPTCHA générique. 86400 correspondent à une journée complète. 604800 correspondent à une semaine. 1296000 correspondent à quinze jours. Les clés préfixées par cf_ s’appliquent lorsque le challenge est identifié comme provenant de Cloudflare. recaptcha_ s’applique lorsqu’il est identifié comme un reCAPTCHA.

Cela explique le symptôme qui fait perdre le plus de temps. Vous trouvez la cause, vous la corrigez, mais le moteur ne renvoie toujours aucun résultat pendant une heure, voire plusieurs jours après un challenge Cloudflare. Il est toujours suspendu. La suspension est conservée dans le processus en cours d’exécution. Le redémarrage du conteneur l’efface, et la recherche suivante essaie de nouveau d’utiliser le moteur. Un simple redémarrage suffit dans ce cas. Il est utile de savoir quand un redémarrage suffit et quand il faut recréer le conteneur avant de reconstruire des images sans raison. Si le moteur échoue de nouveau immédiatement après le redémarrage, votre correction n’a pas fonctionné.

Un paramètre défini par moteur mérite une mise en garde. retry_on_http_error réessaie une requête lorsque le moteur répond avec les codes d’état que vous indiquez. Si un moteur vous bloque, ces nouvelles tentatives envoient davantage de trafic au système qui a déjà identifié votre serveur comme un bot. Ne modifiez pas ce paramètre, sauf si vous contournez les problèmes d’un moteur réellement intermittent.

Documentation sur le tunnel SSH en amont et ce qu’il ne corrige pas

Vérifiée le 17 octobre 2026, la documentation d’administration de SearXNG répond à ce problème avec un tunnel manuel. Vous ouvrez un proxy SOCKS via votre serveur, vous configurez votre navigateur de bureau pour l’utiliser, puis vous répondez manuellement au challenge pendant que le moteur voit l’adresse du serveur.

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

-D 8080 ouvre un serveur SOCKS local sur le port 8080 et transmet les connexions via la connexion SSH. -N n’exécute aucune commande distante et -q le maintient silencieux. Un tunnel fonctionnel n’affiche donc rien et ne se termine pas. Vérifiez-le depuis un deuxième terminal :

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

La première commande doit afficher l’adresse de votre serveur et la seconde, l’adresse de votre poste. Si les deux réponses sont identiques, la requête ne passe pas par le tunnel. Configurez ensuite les paramètres réseau de votre navigateur pour utiliser un proxy SOCKS5 à l’adresse 127.0.0.1 sur le port 8080. Chargez le même service de vérification d’adresse dans le navigateur afin de confirmer qu’il affiche l’adresse du serveur, puis ouvrez le moteur qui vous soumet le challenge. Répondez-y à cet endroit.

Passons maintenant aux limites réelles. Quatre éléments limitent cette méthode. Le cookie remis par le moteur arrive dans votre navigateur de bureau, et SearXNG n’a pas accès aux cookies de votre navigateur. La seule chose qui peut aider votre instance est donc ce que le moteur enregistre pour l’adresse elle-même. Cet enregistrement expire selon un délai choisi par le moteur et non publié. La procédure n’est pas automatisée : vous devrez reprendre la main la prochaine fois. Enfin, sur une instance utilisée par d’autres personnes, le taux de requêtes qui a déclenché le challenge continue de s’appliquer. Le challenge réapparaît donc.

Utilisez cette méthode pour faire fonctionner une instance cet après-midi. Ne concevez pas une instance qui en dépend.

Solution durable : désactivez ou repondérez les moteurs qui vous bloquent

La solution durable la plus simple consiste à ne plus interroger un moteur qui ne peut pas répondre depuis votre serveur. Votre settings.yml commence par use_default_settings: true dans l’image du conteneur. Une entrée sous engines: avec un name correspondant ne remplace donc que les clés que vous indiquez et conserve le reste de la définition par défaut.

use_default_settings: true

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

disabled: true désactive le moteur par défaut tout en le laissant apparaître dans la page des préférences. Un utilisateur qui en a besoin peut ainsi le réactiver pour ses propres recherches. inactive: true le supprime entièrement des paramètres utilisateur. C’est le réglage adapté à un moteur qui ne fonctionnera jamais depuis votre adresse. weight a une autre fonction : ce paramètre modifie le poids des résultats de ce moteur lorsque SearXNG les fusionne et les classe. Une valeur inférieure à 1 permet de conserver un moteur marginal sans le laisser prendre le contrôle de la première page.

Redémarrez le conteneur après la modification, effectuez quelques recherches, puis consultez de nouveau /stats. Une page de statistiques propre avec six moteurs fonctionnels est plus utile qu’une page remplie d’erreurs avec vingt moteurs.

Correctif durable : envoyer les requêtes sortantes via un proxy

SearXNG peut envoyer ses requêtes sortantes vers les moteurs via un proxy. L’adresse visible par le moteur est ainsi modifiée. Configurez-le globalement dans outgoing:, ou par moteur lorsqu’un seul moteur pose problème.

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

Préférez socks5h:// à socks5:// lorsque vous voulez que le proxy résolve le nom d’hôte, car h signifie que le nom est envoyé au proxy au lieu d’être résolu sur votre serveur. Augmentez également le délai d’attente. request_timeout vaut 3.0 secondes par défaut. Un proxy ajoute un aller-retour à chaque requête, et les moteurs qui répondaient auparavant à temps commencent alors à échouer pour cause de délai d’attente. extra_proxy_timeout existe précisément pour cela et ajoute des secondes lorsqu’un proxy est utilisé. Indiquez un nombre entier, par exemple 10. Contrairement à request_timeout, qui accepte les valeurs décimales, extra_proxy_timeout est un entier dans le schéma de configuration. Une valeur comme 10.0 est donc rejetée comme settings.yml non valide, même si l’exemple commenté de la page de documentation des paramètres sortants l’écrit ainsi.

Ce qu’un proxy vous coûte :

• L’opérateur du proxy voit quels moteurs votre instance interroge et à quel moment. TLS (transport layer security) protège les termes de recherche contre leurs journaux, car la requête est incluse dans la requête chiffrée. En revanche, la forme et le rythme de votre trafic leur restent visibles.
• Une adresse de sortie partagée est utilisée avec tous les autres clients qui la paient. S’ils effectuent du scraping, vous héritez de leur réputation, parfois plus vite que du blocage auquel vous tentiez d’échapper.
• Les pools de proxies résidentiels bon marché sont souvent constitués d’appareils grand public dont les propriétaires n’ont pas explicitement accepté de relayer du trafic. Sachez ce que vous achetez.
• using_tor_proxy: true achemine le trafic via Tor, mais les adresses des nœuds de sortie sont publiées intégralement. Un moteur qui bloque généralement les plages d’adresses de datacenters bloque souvent les nœuds de sortie avec la même sévérité, voire davantage.
• La recherche dépend désormais d’un service extérieur à votre serveur. Ce service peut tomber en panne selon son propre calendrier et interrompre vos résultats.

Un proxy déplace le blocage au lieu de le supprimer, et la confidentialité de votre instance inclut désormais un tiers. Si la confidentialité est l’une des raisons pour lesquelles vous auto-hébergez, comparez ce point avec ce qu’une instance auto-hébergée masque réellement et ce qu’elle ne masque pas avant de souscrire à un service.

Correctif durable : utiliser volontairement un ensemble réduit de moteurs

L’option que la plupart des utilisateurs écartent consiste à accepter moins de moteurs. La valeur de SearXNG vient de la fusion des résultats, et une fusion de six moteurs qui répondent systématiquement vaut mieux que vingt moteurs dont la moitié reste suspendue pendant des heures ou des jours. Surveillez /stats pendant une semaine et conservez les moteurs qui présentent un historique fiable depuis votre adresse.

Les moteurs auxquels vous vous authentifiez avec une clé API se comportent différemment, car ils savent qui vous êtes et appliquent un quota au lieu d’essayer de déterminer si vous êtes une personne. En contrepartie, vous devez disposer d’un compte, conserver une clé dans votre fichier de configuration et, généralement, payer une facture. Pour un ou deux moteurs importants pour vous, c’est souvent la solution la moins contraignante.

Prenez cette décision en tenant compte de vos autres outils. Un moteur suspendu est invisible pour tout outil qui lit les résultats via l’API, car l’API JSON interrogée par Open WebUI et les outils similaires renvoie simplement moins de résultats, au lieu de produire une erreur que votre outil pourrait détecter. Si un traitement automatisé dépend de votre instance, interrogez /stats/errors selon une planification au lieu d’attendre que quelqu’un signale que la qualité des réponses s’est dégradée.

Est-ce que cela vaut vraiment la peine de s’acharner ?

Répondez à cette question en comptant les utilisateurs. Une instance utilisée par une seule personne envoie quelques recherches par jour depuis une seule adresse, un rythme que de nombreux moteurs ne contestent jamais. Lorsqu’un moteur vous demande malgré tout une vérification, la solution est simple : retirez-le et vous remarquerez à peine son absence. C’est l’expérience habituelle de l’utilisation de SearXNG pour vous-même sur un petit VPS, sans tunnel ni proxy.

Une instance publique ou partagée est une machine différente qui exécute le même logiciel. Le taux de requêtes déclenche les vérifications et augmente avec chaque utilisateur ajouté. Les vérifications arrivent donc plus vite que la configuration ne peut les absorber. Prévoyez dès le départ un ensemble de moteurs plus réduit. N’oubliez pas non plus que tout proxy ajouté maintenant transmet les recherches d’autres personnes sous votre compte.

Les clients automatisés se situent entre ces deux cas, mais se rapprochent du scénario le plus difficile. Un agent qui exécute plusieurs recherches pour répondre à une question produit des pics qu’aucun humain ne produit. Ainsi, une instance vers laquelle vous dirigez des agents de programmation et des outils de recherche rencontre des vérifications plus tôt que la même instance utilisée manuellement. Dans ce cas, choisissez les moteurs pour leur fiabilité plutôt que pour leur couverture. L’agent pourra ainsi travailler avec les résultats qu’il peut réellement obtenir.

La règle générale est la suivante : luttez pour conserver un moteur lorsqu’il justifie votre auto-hébergement, et retirez-le dans le cas contraire.

FAQ

Pourquoi un moteur SearXNG ne renvoie-t-il toujours aucun résultat après la correction du problème ?

Parce qu’il est encore suspendu. Lorsque SearXNG détecte un challenge ou un refus de la part d’un moteur, il cesse de l’interroger pendant la durée définie dans search.suspended_times. Les valeurs par défaut fournies vont de trois minutes à quinze jours selon le type de refus. La suspension est conservée par le processus en cours. Le redémarrage du conteneur la supprime, et la recherche suivante réessaie donc d’interroger le moteur. Si le moteur échoue de nouveau juste après le redémarrage, votre correction n’a pas fonctionné.

Une erreur CAPTCHA d’un moteur est-elle identique au 429 renvoyé par mon instance ?

Non. Ces erreurs circulent dans des directions opposées. Un 429 envoyé par votre instance à votre navigateur signifie que le limiteur intégré à SearXNG considère votre requête comme automatisée. Vous pouvez configurer ce limiteur. Une erreur CAPTCHA ou de blocage signifie qu’un moteur en amont refuse votre serveur. Cette décision est prise sur une infrastructure que vous ne contrôlez pas. Si la page de résultats se charge et que seuls certains moteurs sont absents, vous êtes face au second cas.

Un VPN ou un proxy sur mon serveur peut-il résoudre les CAPTCHA des moteurs ?

Parfois, mais cela a un coût. Le routage des requêtes sortantes via outgoing.proxies modifie l’adresse vue par le moteur. Cela peut supprimer un blocage associé à la plage d’adresses de votre datacenter. L’opérateur du proxy voit alors les moteurs que vous interrogez et les moments où vous les interrogez. Une adresse de sortie partagée hérite aussi de la réputation des autres clients. Enfin, la latence supplémentaire provoque des timeouts si vous n’augmentez pas request_timeout et extra_proxy_timeout. Tor est disponible via using_tor_proxy, mais ses adresses de sortie sont publiques et font souvent l’objet de challenges.

Puis-je faire résoudre automatiquement les CAPTCHA par SearXNG ?

Il n’existe aucun paramètre pour cela. La méthode documentée par le projet est manuelle : un tunnel SOCKS SSH, votre propre navigateur et une intervention manuelle lors du challenge. Tout système conçu pour répondre automatiquement aux challenges va à l’encontre de la politique déclarée du moteur. Il cesse aussi silencieusement de fonctionner chaque fois que le challenge change. Vous devez alors maintenir un scraper au lieu d’exploiter une instance de recherche. La solution qui reste fonctionnelle consiste à supprimer les moteurs qui bloquent votre adresse.