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.

Fonctionnement des nouvelles tentatives et de la suspension d’un moteur défaillant par SearXNG

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

Deux niveaux contrôlent ce comportement. Ils se trouvent tous les deux sous search: dans settings.yml. Vérifiez le nom de ces clés dans la documentation de configuration de la version que vous utilisez avant de coller quoi que ce soit. Ces clés ont changé entre plusieurs versions. D’après la documentation du 2 September 2026, les valeurs par défaut sont les suivantes :

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

Le premier niveau gère les erreurs ordinaires, comme un délai d’attente dépassé. Le bannissement commence à ban_time_on_fail secondes et augmente à chaque échec consécutif, jusqu’à max_ban_time_on_fail. La limite est de deux minutes par défaut. Un moteur instable redevient donc disponible de lui-même quelques minutes après la disparition du problème.

Le deuxième niveau gère les erreurs décrites dans ce guide. Lorsque SearXNG identifie la réponse comme un challenge ou un refus, et non comme une erreur générique, il applique l’entrée correspondante de suspended_times. Ces valeurs sont bien plus élevées. 86400 secondes 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. Les clés préfixées par recaptcha_ s’appliquent lorsqu’il est identifié comme provenant de reCAPTCHA.

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

Un paramètre propre à chaque moteur mérite une mise en garde. retry_on_http_error réessaie une requête lorsque le moteur répond avec l’un des 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. Laissez ce paramètre inchangé, sauf si vous gérez un moteur réellement instable.

Les documents en amont sur le tunnel SSH, et ce qu’il ne corrige pas

Vérifiée le 2 septembre 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 achemine les connexions via la session SSH. -N n’exécute aucune commande distante et -q le maintient silencieux. Un tunnel fonctionnel n’affiche donc rien et ne rend pas la main. 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 de travail. 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 avec un proxy SOCKS5 à l’adresse 127.0.0.1 et sur le port 8080. Chargez le même service de vérification d’adresse dans le navigateur pour confirmer qu’il indique l’adresse du serveur, puis accédez au moteur qui vous soumet le challenge. Répondez-y depuis le navigateur.

Passons maintenant aux limites de cette méthode. Quatre éléments la limitent. Le cookie remis par le moteur est enregistré dans le navigateur de votre poste, et SearXNG n’a pas accès aux cookies de votre navigateur. La seule chose qui puisse 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, qui ne le publie pas. Aucune partie de la procédure n’est automatisée : vous devrez reprendre la main la prochaine fois. Enfin, sur une instance utilisée par d’autres personnes, le débit de requêtes qui a déclenché le challenge continue. Le challenge réapparaît donc.

Utilisez cette méthode pour remettre une instance en fonctionnement cet après-midi. Ne construisez pas une instance autour de cette solution.

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 les requêtes sortantes destinées aux moteurs via un proxy, ce qui modifie l’adresse que le moteur voit. Configurez-le globalement sous outgoing:, ou par moteur lorsqu’un seul moteur rencontre le problème.

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

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 le délai d’attente en même temps. request_timeout vaut 2.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 par expiration du délai. extra_proxy_timeout est prévu précisément pour cela et ajoute des secondes lorsqu’un proxy est utilisé.

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) empêche les termes recherchés d’apparaître dans ses journaux, car la requête se trouve dans la requête chiffrée, mais il peut voir la structure et le rythme de votre trafic.
• Une adresse de sortie partagée l’est avec les autres utilisateurs qui la paient. S’ils effectuent du scraping, vous héritez de leur réputation, parfois plus vite que le blocage auquel vous cherchiez à échapper.
• Les pools de proxies résidentiels bon marché sont souvent constitués d’appareils grand public dont les propriétaires n’ont pas accepté consciemment de transporter 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, et un moteur qui bloque les plages d’adresses des datacenters bloque généralement 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 vos résultats avec lui.

Un proxy déplace le blocage au lieu de le supprimer, et la confidentialité de votre instance inclut désormais un tiers. Si une politique de confidentialité concise justifie votre auto-hébergement, comparez-la à ce qu’une instance auto-hébergée masque réellement et ce qu’elle ne masque pas avant de souscrire à quoi que ce soit.

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

L’option que la plupart des utilisateurs négligent consiste à accepter moins de moteurs. La valeur de SearXNG vient de l’agrégation, et une agrégation de six moteurs qui répondent à chaque fois vaut mieux que vingt moteurs dont la moitié reste suspendue pendant une journée entière. 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 qui vous sont importants, c’est souvent la solution la moins contraignante.

Tenez compte de vos autres outils. Un moteur suspendu est invisible pour tout ce 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 processus automatisé dépend de votre instance, interrogez /stats/errors selon une fréquence définie au lieu d’attendre que quelqu’un se plaigne de la dégradation des résultats.

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 toujours 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. Ces valeurs par défaut vont d’une heure à quinze jours selon le type de refus. La suspension est conservée dans 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 la même chose que le 429 renvoyé par mon instance ?

Ces erreurs circulent dans des directions opposées. Un 429 renvoyé par votre instance à votre navigateur indique que le limiteur de SearXNG a considéré votre requête comme automatisée. C’est un paramètre que vous pouvez configurer. Une erreur CAPTCHA ou de blocage indique 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, mais que seuls certains moteurs sont absents, vous êtes dans le second cas.

Un VPN ou un proxy sur mon serveur résoudra-t-il 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 l’heure de ces requêtes. Une adresse de sortie partagée arrive aussi avec 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 largement l’objet de challenges.

Puis-je configurer SearXNG pour résoudre automatiquement le CAPTCHA ?

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