How to Fix SearXNG CAPTCHA Errors from Search Engines

Wetin SearXNG CAPTCHA error mean

SearXNG CAPTCHA errors dey come from the engines wey your instance dey query. Your server ask engine for results, the engine reply with challenge page instead of results, and SearXNG record error against that engine because nothing dey inside the reply wey e fit parse. Your instance dey healthy. One machine wey you no control decide say your request no look like person request.

Na this one fact dey decide every fix wey follow. Dem make the decision for the engine own hardware, so nothing for your settings.yml fit override am. Wetin you fit change na the address wey the request dey leave from, the engines wey you query at all, and how your instance go behave once engine start reject requests.

Two failures wey look the same, and how you fit tell dem apart

The first failure na your own instance wey dey answer HTTP 429 (too many requests) to your own browser. Na the SearXNG limiter cause am, the bot detection layer wey dey in front of the search endpoint. E dey run for your box and na you dey configure am. the limiter wey dey return 429 to your own users na separate problem with separate settings, and none of the advice below apply to am.

The second failure dey upstream. Results page dey load normally, but one or more engines no dey show for the results or dem carry error notice. Nothing for your instance reject anything. Na an engine reject your server.

• If page no go load, or search endpoint answer 429: check your limiter.
• If page load and results no plenty, or an engine get error flag: check upstream, and continue reading.

Both fit happen for the same instance, and dem fit affect each other, because limiter wey you set too loose go allow traffic wey increase your outgoing query rate. Diagnose dem one by one.

Why SearXNG engines dey return CAPTCHA errors for VPS, but no dey return am for my laptop?

Na the address wey request come from cause am. Your home connection get address from consumer ISP (internet service provider) range. Plenty ordinary people don share that range over time. Your VPS get address from datacentre range, and dem don publish those ranges. Anybody fit check which addresses belong to hosting provider. Engine wey want block scrapers go first treat requests from hosting ranges as suspicious, because only small part of traffic from those ranges come from human wey dey use browser.

Other things still dey add to the problem. Your instance sends one request to each engine for every user search. So even small number of users fit create request rate from one address wey one person alone no go create. By design, SearXNG no keep session with the engine and e no send long lived cookie. So every request dey arrive without any previous history. The address fit also get history wey you no create, because providers dey recycle addresses. The previous tenant fit don scrape from that address for months.

The refusal no always show as obvious failure. Engine fit answer with 403, 429, or HTTP 200 plus challenge page inside the response body. The last one dey confuse people. Status code check go show say engine dey okay, while SearXNG finds zero results inside the response. Na why you need read your own instance error report instead of using curl on the engine and checking only the status line.

Read wetin your instance report before you change anything

Every fix below start with the name of the engine wey dey fail and the reason wey your instance record for am. SearXNG dey show both. The /stats page list engines with their error counts and reliability, while /stats/errors return the error detail as JSON, wey easier to save and compare next week. Open dem for the browser wey you normally use for the instance.

The container log carry the same events as dem happen. The service name here na the one wey dem use for the compose file published with the container documentation, so use your own if e different.

docker compose logs -f core

Run a search wey go fail while the log dey follow. You suppose see entry for the failing engine as the search dey run. Write down the engine name and the exact reason string wey your instance print. No copy engine name from blog post, including this one. The set of engines wey challenge datacentre addresses dey change from month to month, and the engine wey fail for you fit work perfectly for whoever write the post wey you dey read.

If the results page no show any error but the results dey small, check display_error_messages for that engine. E default to true, and instance wey don turn am off dey hide the one message wey you need.

SearXNG dey retry and suspend engine wey dey fail

SearXNG no dey keep hammering engine wey no gree am. Engine wey dey fail go enter suspension, and while e dey suspended, SearXNG go skip am completely. Na so broken engine fit turn to engine wey just disappear without any clear error.

Two layers dey control this, and both dey under search: for settings.yml. Confirm these key names and values against searx/settings.yml for the version wey you dey run before you paste anything, because dem don move between releases. Also, example for the settings documentation page still dey show longer suspension times than the file wey SearXNG actually loads. As shipped for searx/settings.yml on 10 October 2026, the defaults be:

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

The first layer dey handle normal failures like timeout. The ban starts at ban_time_on_fail seconds and dey increase with every failure wey happen consecutively, up to max_ban_time_on_fail. By default, two minutes na the maximum. So, flaky engine fit recover by itself within some minutes after the problem don stop.

The second layer dey handle the failures wey this guide dey discuss. When SearXNG recognise the reply as challenge or refusal instead of general error, e apply the matching entry from suspended_times, and most of those numbers much bigger. 180 seconds na three minutes, for plain refusal or 429. 3600 na one hour, for general CAPTCHA. 86400 na complete day. 604800 na one week. 1296000 na fifteen days. Keys wey start with cf_ apply when SearXNG recognise the challenge as Cloudflare one, while recaptcha_ apply when e recognise am as reCAPTCHA.

This explain the symptom wey dey waste the most time. You find the cause, you fix am, but the engine still no return result for one hour, or for days after Cloudflare challenge. E still dey suspended. The running process dey keep the suspension state, so when you restart the container, e clear the suspension and the next search go try the engine again. Plain restart dey enough for this case. Before you start rebuilding images without reason, e good make you know when restart dey enough and when you need recreate the container. If the engine fail again immediately after restart, your fix no work.

One setting wey apply to each engine need warning. retry_on_http_error dey retry request when the engine answer with the status codes wey you list. If engine dey block you, retries go send more traffic to the system wey don already decide say your server na bot. Leave am as e be unless you dey work around engine wey genuinely dey fail from time to time.

The SSH tunnel upstream documents, and wetin e no fit fix

Checked on 10 October 2026, the SearXNG admin documentation answer this problem with manual tunnel. You go open SOCKS proxy through your server, point your desktop browser to am, then answer the challenge by hand while the engine dey see your server address.

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

-D 8080 dey open local SOCKS server for port 8080 wey dey forward through the SSH connection. -N no dey run any remote command, and -q keep am quiet, so healthy tunnel no go print anything and e no go return. Check am from another terminal:

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

The first command suppose print your server address, and the second one suppose print your desktop address. If both answers dey the same, e mean say request no dey pass through the tunnel. Then set your browser network settings to SOCKS5 proxy for 127.0.0.1 port 8080. Load the same address checker for the browser to confirm say e dey report the server address, then visit the engine wey dey challenge you. Answer the challenge there.

Now make we talk the honest part. Four things limit this method. The cookie wey the engine give you go land for your desktop browser. SearXNG no get access to your browser cookies, so the only thing wey fit help your instance na wetin the engine record against the address itself. That record go expire according to schedule wey the engine choose and no publish. No part of this procedure dey automated, so next time you go still need return to the keyboard. For instance wey other people dey use, the query rate wey trigger the challenge still dey run, so the challenge go come back.

Use am to make one instance work this afternoon. No build instance around am.

Fix wey go last: drop or reduce priority for engines wey dey block you

The cheapest solution wey go last na to stop querying any engine wey no fit serve your server. Your settings.yml starts with use_default_settings: true inside the container image. This means say an entry under engines: wey get matching name go override only the keys wey you list, while the other parts of the default definition remain as dem be.

use_default_settings: true

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

disabled: true switches the engine off by default, but e still dey the preferences page. This means user wey want am fit switch am on again for their own searches. inactive: true removes the engine completely from user settings. Na this one you need for an engine wey no go ever work from your address. weight get another function: e controls how much the engine results count when SearXNG merges and ranks them. So, weight wey dey below 1 fit keep a weak engine available without allowing am take over the first page.

Restart the container after you edit am. Run some searches, then check /stats again. Stats page wey clean and get six working engines dey more useful than page wey full of errors and get twenty engines.

Fix wey go last: send outgoing requests through proxy

SearXNG fit send outgoing engine requests through proxy, and this go change the address wey engine dey see. Set am globally under outgoing:, or per engine if na only one engine get the problem.

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

Prefer socks5h:// instead of socks5:// when you want proxy to resolve the hostname, because h mean say dem go send the name to proxy instead of looking am up for your server. Increase the timeout budget at the same time. request_timeout dey default to 3.0 seconds, proxy adds one round trip to every request, and engines wey dey answer on time before fit start fail as timeout instead. extra_proxy_timeout dey for exactly this purpose and e adds seconds when proxy dey use. Write am as whole number like 10: the settings schema expect integer, and value like 10.0 go reject as invalid settings.yml.

Wetin proxy go cost you:

• Proxy operator go see which engines your instance dey query and when. TLS (transport layer security) dey keep search terms out of their logs, because query dey inside encrypted request, but dem fit read the shape and timing of your traffic.
• Shared exit address dey shared with anybody else wey dey pay for am. If dem scrape, you go inherit their reputation, sometimes faster than the block wey you dey try escape.
• Cheap residential proxy pools often dey built from consumer devices wey their owners no knowingly agree to carry traffic. Know wetin you dey buy.
• using_tor_proxy: true dey route through Tor, but dem publish exit node addresses complete, and engine wey dey challenge datacentre ranges usually dey challenge exit nodes at least as hard.
• Search now depend on service wey dey outside your server. E fit fail according to its own schedule and carry your results go with am.

Proxy dey move the block instead of removing am, and the privacy story of your instance now include third party. If na short privacy story make you self-host, compare am with wetin self-hosted instance really dey hide and wetin e no dey hide before you sign up for anything.

Fix wey go last: run smaller engine set on purpose

The option wey plenty people dey skip na to accept fewer engines. The value of SearXNG dey for the merge, and merge of six engines wey dey answer every time better pass twenty engines where half dey suspended for hours or days at once. Monitor /stats for one week, then keep the engines wey get clean record from your address.

Engines wey you authenticate with an API key dey behave differently, because the engine know who you be and dey enforce quota instead of guessing whether you be person. The trade-off na account, key wey dey inside your settings file, and usually bill. For one or two engines wey matter to you, this one often na the path wey get the least wahala.

Decide this with your other tools for mind. Suspended engine no dey visible to anything wey dey read results through the API, because the JSON API wey Open WebUI and similar tools dey query simply return fewer results instead of error wey your tool fit notice. If something automated depend on your instance, poll /stats/errors on schedule instead of waiting for person to complain say the answers don worse.

E worth the fight at all?

Answer dey depend on how many users dey use am. Instance wey one person dey use go send only small number of searches every day from one address. Many engines no dey challenge this kind rate. If one engine challenge you, the fix cheap: remove the engine, and you hardly go notice say e don comot. Na the normal experience be this when you run SearXNG for yourself on a small VPS, and you no need tunnel or proxy.

Public or shared instance na different machine wey dey run the same software. Query rate na wetin dey trigger the challenge. E dey increase with every user wey you add, so challenges go start come faster than any configuration fit handle. Plan for smaller engine set from the beginning. Also remember say any proxy wey you add now go carry other people searches under your account.

Automated clients dey between these two cases, but dem dey close to the harder one. Agent wey run several searches to answer one question go create bursts wey no human dey create. So instance wey you point coding agents and research tools to go meet challenges earlier than the same instance wey people dey drive by hand. If na this you dey do, choose engine set based on reliability, not breadth. Make the agent work with results wey e fit actually get.

The rule wey hold be this: fight for an engine when na the reason you self-host, and remove am when e no be.

FAQ

Why engine go still return nothing after I fix the problem?

Because e still dey suspended. When SearXNG recognise a challenge or refusal from an engine, e stop querying that engine for the period wey dem set for search.suspended_times, and the shipped defaults fit run from three minutes reach fifteen days, depending on the refusal type. The suspension dey inside the running process, so if you restart the container, e go clear, and the next search go try the engine again. If the engine fail again immediately after restart, your fix no work.

Engine CAPTCHA error na the same thing as the 429 wey my instance return?

Dem dey move for opposite directions. A 429 from your instance go your browser na SearXNG own limiter wey decide say your request look automated, and na you fit configure am. A CAPTCHA or block error mean say upstream engine dey refuse your server, based on decision wey happen for hardware wey you no control. If the results page load and na only some engines dey miss, na the second case you dey see.

VPN or proxy for my server fit fix engine CAPTCHAs?

Sometimes, but e get cost. If you route outgoing requests through outgoing.proxies, e go change the address wey the engine see, and this fit clear block wey dem tie to your datacentre range. The proxy operator go then see which engines you dey query and when. A shared exit address fit come with other customers' reputations attached. The extra latency fit cause timeouts unless you increase request_timeout and extra_proxy_timeout. Tor dey available through using_tor_proxy, but dem publish the exit addresses and engines dey challenge dem often.

I fit make SearXNG solve the CAPTCHA automatically?

No setting dey for that. The method wey the project document na manual: an SSH SOCKS tunnel, your own browser, and you personally handle the challenge. Anything wey you build to answer challenges automatically dey against the engine policy, and e go quietly break every time the challenge change. This go leave you maintaining a scraper instead of running a search instance. Remove the engines wey block your address; na this answer dey keep working.