Fix SearXNG engine timeouts and KeyError
Read the SearXNG service log and /stats to tell a timeout from a suspended engine or a crash like KeyError, then fix each one in settings.yml.
What a SearXNG engine error means
A SearXNG engine error on the results page means one engine failed while the rest of the search worked. SearXNG queries every selected engine in parallel, keeps whatever comes back in time, and then reports the engines that did not answer. The page tells you which engine failed and the class of the failure. The service log tells you the cause.
Three different problems produce that red message, and they need opposite fixes. An engine can miss the deadline, which is a timeout. It can be suspended, which means SearXNG refused to call it at all because of earlier failures. Or the request can succeed and the parser can crash on the response, which is where KeyError comes from. Classify what you have before you change any setting, because raising a timeout does nothing for a crashed parser, and updating the image does nothing for an engine that is simply slow. The steps below assume a SearXNG instance you run yourself, because they all need the service log.
Read the message on the results page first
Under the results, SearXNG shows a collapsible section labelled Response time when timing data and results are available, or Messages from the search engines otherwise. Open it. Each engine that answered is listed with its response time. Each engine that did not is listed with its name and a short error type. The failed engine's name links to its own stats page, with the tooltip View error logs and submit a bug report.
That error type is generated from the exception SearXNG caught, not written by a human. SearXNG takes the exception class, prefixes it with its Python module, and drops the prefix when the module is builtins. So the shape of the text is your first classifier. A bare name with no dot, such as KeyError, is a Python builtin, which means code inside SearXNG raised it while handling the response. A curl_cffi. prefix, for example curl_cffi.requests.exceptions.Timeout, means the HTTP client gave up on the request. SearXNG moved its outgoing requests from httpx to curl_cffi in September 2026, so an instance running an older image reports the same failures with an httpx. prefix instead. A searx.exceptions. prefix means SearXNG read the response and recognised it, for example as a CAPTCHA (completely automated public Turing test to tell computers and humans apart) or as a too-many-requests reply.
One error type is a hand-written string rather than an exception name: the lowercase word timeout, with no dot in it. That one means the engine's worker thread was still running when the whole search ran out of time, so SearXNG stopped waiting and moved on without it. It is not the same as a timeout class from the HTTP client, which means the single HTTP request hit its own deadline first. Both are timeouts, but the first one points at the search deadline and the second points at the engine, and section 6 below treats them differently.
Copy the error type down exactly as your page prints it. Do not match it against an example from a guide, because the useful detail is which module the name came from, and that differs per instance and per engine version.
Where the engine error line appears in the log
The results page gives you a class. The log gives you the cause. Every engine logs under the logger name searx.engines.<engine name>, so that string is the filter that turns a noisy log into the few lines you need.
With the Compose file that SearXNG's container documentation ships, the service is named core:
docker compose logs --since 10m core | grep searx.engines
docker compose logs -f coreOlder Compose files, including the ones from the separate searxng-docker repository, name the service searxng. Run docker compose config --services if you are not sure which you have. For a container started by hand with docker run --name searxng, use docker logs --since 10m searxng. For a source install behind uWSGI, the same lines go to that service's journal:
sudo journalctl -u uwsgi --since "10 min ago" | grep searx.enginesOn Debian and Ubuntu the packaged uWSGI is driven through an init wrapper rather than a plain systemd unit, so if that journal is empty, look for the application log under /var/log/uwsgi/ instead.
Now read what you got. At the default log level you will not see a Python traceback. SearXNG's production log level is WARNING, and exception contexts are logged at WARNING too, so they remain visible in production. What does appear for each failure is a warning line from the engine's logger that starts with ErrorContext(. It holds the file and line number where the failure was recorded, that line of source code, and the exception class. For a parser crash the file sits under searx/engines/; check the recorded function and source line to distinguish response parsing from request preparation in the same module. A line inside the response parser shows the failure happened while reading a response that did arrive, and the quoted source line usually shows the key or index it was reading. For a timeout the recorded class is the HTTP client's timeout. When the whole search ran out of time there is also an error line reading engine timeout, which names the engine and nothing else. No line at the default level tells you how long the request took or the limit it was allowed. That detail is a debug message: general.debug: true in settings.yml switches logging to debug level and adds timeout diagnostics with the search duration and timeout, plus separate exception text, which for a KeyError is the missing key. It is a development setting and should not stay on for an instance other people use. The ErrorContext lines come from the same error recorder that feeds /stats, so with general.enable_metrics: false they disappear as well.
What /stats tells you about failure rate and response time
The log explains one event. /stats on your own instance explains whether that event is a pattern. The engine table has five columns: Engine name, Scores, Result count, Response time, and Reliability.
Read Reliability first. It is 100 minus the summed percentage of recorded primary errors for that engine, and each error's share of sent requests is rounded to the nearest 5 percent before it is subtracted. So 100 does not mean nothing failed. It means each recorded primary error context rounded to zero separately; their combined failure rate can exceed 2.5 percent. You can sort on it directly with /stats?sort=reliability. An engine sitting at 100 can still have repeated failures, and the score alone establishes neither their cause nor whether a config change is needed. An engine near 0 has a poor recorded history, but suspensions expire automatically and a successful subsequent request resets suspension state.
Response time is reported as a total plus the HTTP part, and the processing part is the total minus the HTTP part. That split is what separates a slow network path from slow parsing work. Compare the total against the timeout that engine is allowed. An engine whose median total already sits just under the deadline will time out on every query where the upstream is slightly slower than usual, which is why the failure looks random.
Click the engine name for its own page. It lists Errors and exceptions and Warnings, each with a percentage. That is the failure history rather than one event, so it shows whether the same error context has recurred, though the rounded percentages do not give an exact event count.
Two limits on this page are worth knowing. The metrics live in process memory, so a restart resets every counter and a freshly restarted instance has no request history. And if general.enable_metrics is set to false, the page has nothing to report at all. If you run more than one worker process, the counters belong to the worker that served your request, so the numbers can move between reloads.
Classify the failure into one of three cases
A timeout. The error type is the word timeout, or a timeout class from the HTTP client (curl_cffi. on current images, httpx. on older ones). Timeout failures do not populate the response-time histograms, so /stats can show older successful timings or no timing for that engine. The log shows an engine timeout line or an ErrorContext warning naming a timeout class; a request made inside an engine module can put that warning under searx/engines/ too.
A suspension. SearXNG never called the engine. It stores the reason from the earlier failure and reports that stored reason for as long as the suspension lasts. The signature is timing: the error appears immediately instead of after a wait, and the reason usually names something the upstream said, such as access denied or too many requests.
Upstream breakage. The error type is a Python builtin such as KeyError, IndexError or TypeError, and the log holds an ErrorContext warning whose function and source line identify response parsing under searx/engines/. The engine answered. Its answer no longer matches what the parser expects.
Fix a SearXNG engine timeout by raising both timeouts
There are two timeout settings, and raising only one of them often changes nothing. outgoing.request_timeout is the default deadline for a single HTTP request to an engine, and a per-engine timeout overrides it for that engine. outgoing.max_request_timeout is the upper limit on the whole search.
Here is the part that catches people. Without a query-level timeout_limit, the deadline for the whole search is the largest timeout among the engines selected for that search, and when max_request_timeout is set, the search deadline becomes the smaller of those two numbers. So a per-engine timeout: 10.0 on an instance with max_request_timeout: 5.0 gives that search five seconds, not ten, because SearXNG stops waiting for the worker thread when the search deadline passes; it does not terminate the thread. The engine then reports the plain timeout error type. Raise both values, or the larger one is ignored.
use_default_settings: true
outgoing:
request_timeout: 5.0
max_request_timeout: 15.0
engines:
- name: wikidata
timeout: 10.0With use_default_settings: true, entries under engines are merged into the shipped defaults by name, so those two lines change one engine and leave every other engine untouched. The name has to match the default name exactly, spaces included, or you have quietly defined a new engine that does nothing.
Know the cost before you raise anything. Because the search deadline is taken from the slowest engine in the search, a single engine allowed ten seconds makes every query that includes it able to take ten seconds, and users feel that on successful searches as well as failing ones. Prefer a per-engine timeout over a large global request_timeout. Also check outgoing.retries: each retry spends its time inside the same search deadline, so retries on a slow engine turn a sometimes-slow engine into a reliable timeout.
Then restart so the file is read again. A bind-mounted settings.yml needs a restart and nothing more, since the image did not change, which is the difference between restarting and rebuilding a Compose service.
docker compose restart core
docker compose logs --since 1m coreCheck that log before you reload the browser. Invalid YAML stops SearXNG from starting, and the parse error names the line number, so a container that keeps restarting after an edit is almost always an indentation mistake rather than a broken engine.
Fix a suspension by waiting it out or disabling the engine
A suspension is SearXNG protecting itself and your server's address. After a failed request it stops calling that engine for a while. The short kind lasts the smaller of search.ban_time_on_fail and search.max_ban_time_on_fail, which with the shipped values of 5 and 120 is a flat 5 seconds. SearXNG counts consecutive failures, but the count does not lengthen the suspension, so the 120 second value only matters if you set ban_time_on_fail above it. A single successful search resets it. Only request failures suspend an engine: HTTP timeouts, SSL and HTTP errors, and the recognised refusals below. A parser crash such as KeyError and the search-wide timeout are recorded but do not suspend anything. So a brief red message that clears itself within seconds needs no action.
Specific upstream responses get their own, longer suspensions, listed under search.suspended_times. As of 6 November 2026, the current settings documentation lists one hour after a too-many-requests response and one day after access denied or a CAPTCHA, while the current source settings.yml contains three minutes for too many requests or access denied and one hour for a CAPTCHA. Cloudflare and reCAPTCHA responses keep much longer values: one day for a Cloudflare access denied, seven days for a reCAPTCHA, and 1296000 seconds, which is fifteen days, for a Cloudflare CAPTCHA. Check the settings.yml in the image you run and your local overrides to establish the values your instance uses. Shortening those numbers to make the message disappear is the wrong move, because retrying an engine that just blocked you is what deepens the block. When the reason names a CAPTCHA, the cause is on the other side and it has its own guide: a CAPTCHA returned by an engine you are querying.
If an engine fails often enough that you would rather stop asking it, disable it instead of deleting it:
engines:
- name: qwant
disabled: truedisabled: true keeps the engine in the list but off by default, so a user can still switch it on in preferences, and you can switch it back with one line. To drop it from the instance completely, use the remove list under use_default_settings.engines. Which engines earn their place is a longer decision, covered in which SearXNG engines to enable and which to turn off.
Do not reach for display_error_messages: false. It hides the message for that engine and changes nothing else, so the engine keeps failing and you have thrown away the only signal you had.
Why does a SearXNG engine fail with KeyError?
A KeyError from an engine's response parser means the parser asked the response for a field that was not in it. Engine modules read the upstream answer, often JSON, and pull named fields out of it. When the upstream renames a field, stops sending one, or returns a different document altogether such as a consent or block page, that lookup fails and Python raises KeyError naming the field it wanted. IndexError is the same fault against a list that came back shorter than expected. TypeError usually means a field arrived as null, meaning no value, where the parser expected an object it could read into.
No setting in settings.yml fixes this, because the defect is in code that no longer matches the data. You have two honest options: update, or disable.
Update first. Engine parsers are repaired in SearXNG itself, usually quickly, so an instance that has not been pulled for months is the common reason a reader meets this error at all. Pin a tag instead of running latest, so you know which version you moved to and can move back to the one that worked. The Compose file reads the tag from SEARXNG_VERSION in .env:
SEARXNG_VERSION=2026.10.16-0ce72dd2cdocker compose pull core
docker compose up -d core
docker compose logs --since 2m coreTags are published as a date plus a commit hash, and the one above is an example tag from 16 October 2026. Read the current tag from the image's own tag list rather than copying that string, then bring up only that one service so the rest of the stack keeps running. Repeat the failing search afterwards and check the engine's Reliability on /stats again, since the counters were reset by the restart and now measure only the new version.
If the parser fix has not been released yet, search the SearXNG issue tracker at github.com/searxng/searxng/issues for the engine name. Someone has usually filed it with the same error. Disable the engine until the fix ships, then remove the disabled: true line.
An engine error is not a 429 from your own limiter
The boundary matters, because the two look similar in a browser and the fixes point in opposite directions.
Everything above is your instance telling you that an upstream engine failed. Your instance itself worked: it answered the request and rendered a results page, with one row reporting a failure. If instead your own instance replies with HTTP 429 Too Many Requests, the whole page or API call fails and there are no engine messages to read, because the search never ran. That is SearXNG's limiter, a separate subsystem with its own configuration file and its own Valkey dependency. Start with SearXNG answering your own requests with 429, and read how limiter.toml and Valkey fit together before changing limiter settings.
There is a second, easier confusion. A too-many-requests error type inside Messages from the search engines is the upstream engine rate limiting your server's outbound address. It points the other way, and no limiter setting on your instance affects it. The levers there are querying fewer engines per search, spreading the load, or presenting a different exit address.
A routine you can repeat
- Reproduce with one engine only, by prefixing the query with that engine's bang shortcut, for example
!ddgfollowed by your search terms. - Open the Response time or Messages from the search engines section and write down the error type exactly as printed.
- Filter the service log for
searx.enginesaround that timestamp and decide whether theErrorContextfunction and source line identify response parsing undersearx/engines/or record a timeout. - Open
/stats, then the engine's own page, and read Reliability plus the response time split. - Apply the single fix that matches the class, restart, and go back to step 1 to confirm it.
The reason this order works is that each step narrows the cause before any setting changes. Editing settings.yml first is what turns a fifteen-minute fix into an afternoon, because a timeout raised on a crashed parser produces exactly the same red message, and now you have two changes to undo.
FAQ
Why does my SearXNG results page say an engine is unresponsive?
Because that engine did not return usable results before the search finished, while the other engines did. Open the Response time or Messages from the search engines section under the results to see the engine name and the error type. A bare exception name such as KeyError means SearXNG code raised a builtin exception; check the recorded function and source line to confirm a response parser crashed. A name starting with curl_cffi., or httpx. on images older than September 2026, means the HTTP request failed or timed out. The lowercase word timeout means the whole search ran out of time while that engine was still working. Then read the service log filtered on searx.engines for the cause behind the class.
How do I raise the timeout for one SearXNG engine?
Add a per-engine timeout under engines in settings.yml, matching the engine's default name exactly, and keep use_default_settings: true so the entry merges into the defaults instead of replacing them. Check outgoing.max_request_timeout at the same time: without a query-level timeout_limit, the search deadline is the largest timeout among the selected engines, capped by max_request_timeout, so a per-engine value above that cap has no effect. Restart the service and watch the log to confirm the file parsed.
What does a KeyError from a SearXNG engine mean?
It means code asked for a missing dictionary key; when the recorded function and source line identify response parsing, the parser asked the engine's response for a field that was absent. The ErrorContext warning in the log names the file and source line, which distinguish response parsing from request preparation in the same engine module. The usual cause is an upstream API or HTML change that a newer SearXNG release already handles, so update to a pinned image tag and retest. Disable that engine while you wait if the fix is not out yet.
How long does SearXNG suspend an engine after it fails?
Ordinary request failures suspend it for the smaller of search.ban_time_on_fail and search.max_ban_time_on_fail, which with the shipped values of 5 and 120 is a flat 5 seconds every time. Consecutive failures do not make it longer, and one successful search clears the state. Specific upstream refusals use the longer values under search.suspended_times: the current documentation lists one hour for too many requests and one day for access denied or a CAPTCHA, while the current source settings.yml contains three minutes, three minutes and one hour respectively. Both list one day for a Cloudflare access denied, seven days for a reCAPTCHA, and fifteen days for a Cloudflare CAPTCHA. Check your image's settings.yml and local overrides for the effective values. During a suspension SearXNG does not contact the engine and repeats the stored reason from the original failure.
Is an engine error the same as my instance returning 429?
No. An engine error is one row inside a results page that your instance successfully produced, and it describes an upstream engine failing. A 429 from your instance means the request never reached the search stage, because SearXNG's limiter rejected it, and that is configured in limiter.toml with Valkey behind it. If you see no results page and no engine messages at all, treat it as a limiter problem rather than an engine problem.