Fix SearXNG Rate Limits, Captchas, Redis Errors, and Broken Search Engines

If you run a public or API-enabled SearXNG instance, keeping it alive in Docker is the easy part. This SearXNG troubleshooting guide walks through config fixes for rate limits, captcha walls, Redis errors, broken engines, and messy JSON output. So your instance stays useful under real traffic, not just running in a container.

SearXNG doesn't have its own search index; it forwards every query to engines like Google and Bing, which means your server looks like a bot the moment traffic grows. That single fact is behind almost every problem this SearXNG troubleshooting guide covers, including captchas, bans, missing results, and slow responses.

The engines don't know a human is behind the request. They only see volume and patterns, and once those patterns look automated, they throttle or block your IP.

Fixing that at the source, not just restarting containers, is step one in this SearXNG troubleshooting guide.

If you haven't deployed the base instance yet, the self-hosted SearXNG Docker setup guide covers the initial installation step by step.

SearXNG ships a built-in bot-protection feature called the limiter, and turning it on is the single most useful fix in this SearXNG troubleshooting guide for instances getting attacked by bots or scrapers.

To fix the SearXNG rate limits, follow the steps below:

Open your settings.yml and add this under the server: section:

Still in settings.yml:

If SearXNG runs in Docker and Valkey runs in a separate container, replace localhost with the Valkey container's service name from your docker-compose.yaml, for example, valkey://redis:6379/0.

The limiter can only tell IPs apart if X-Forwarded-For and X-Real-IP are set correctly by your reverse proxy. In your reverse proxy config, make sure these headers are forwarded.

You must tune the /etc/searxng/limiter.toml. Don't copy the whole default file, just override what you need:

To apply the changes, restart the container:

This SearXNG troubleshooting guide recommends running with limiter defaults for about a week, watching logs, then adjusting pass_ip/block_ip only for addresses causing real trouble.

Captcha walls appear when an upstream engine decides your IP looks automated. SearXNG logs this as SearxEngineCaptchaException, and by default, that engine gets suspended for 86400 seconds (one day) before SearXNG tries it again.

To fix SearXNG Captcha walls, follow these steps:

Check the logs to verify it's a captcha:

In settings.yml, under search::

Google Captchas use recaptcha_SearxEngineCaptcha at 604800 seconds (one week), and Cloudflare Captchas use cf_SearxEngineCaptcha at 1296000 seconds (15 days). These are long because both platforms are aggressive against repeat offenders.

Spread queries across more engines in settings.yml under engines: instead of holding one or two, and keep the limiter from step one active. Fewer repeated hits on the same engine means fewer captchas over time.

No command removes a captcha instantly; the fix is lowering how bot-like your traffic looks, which this SearXNG troubleshooting guide ties directly back to the limiter setup above.

Most Redis errors reported for SearXNG are actually Valkey connection problems, since SearXNG now uses Valkey (Redis-compatible) for both the limiter and caching.

Check that the container is running:

Look for the redis or valkey service status. If it's not "Up," check its logs:

Test the connection directly from inside the SearXNG container:

A working connection returns PONG. If it doesn't, the network path between SearXNG and Valkey is broken, not your settings file.

Fix the URL mismatch. Inside Docker Compose, SearXNG must use the Valkey service name, not localhost:

Recreate the network if it's missing entirely:

If limiter is enabled but Valkey isn't reachable, SearXNG doesn't throw a visible error; it just silently fails to activate bot protection, so this check matters even if the site looks fine.

When an engine's HTML or API changes, SearXNG doesn't crash; it quietly drops that engine's results, which looks like "missing results" rather than a clear error.

To resolve SearXNG missing search engines errors, follow the steps below:

Use the command below to find which engine is failing:

Each exception maps to a different cause:

Parser fixes for broken engines ship regularly:

In settings.yml, set disabled: true on the specific engine instead of letting it waste request quota:

Using 8 to 10 engines instead of just 2 or 3 means one broken engine won't hurt your results much. This SearXNG troubleshooting guide treats engine redundancy as cheap insurance against single points of failure.

If you're calling SearXNG from an app or AI tool, JSON errors always trace back to the formats list under search:; only html is allowed by default.

Enable JSON in settings.yml:

Restart to apply it:

Test the API call:

If it still fails, an engine may be failing mid-request and producing incomplete data downstream. Pair this fix with the engine checks above, rather than treating it as a separate bug.

An outbound ban means an engine has flagged your entire server IP, not just one request. SearXNG maps this to SearxEngineAccessDeniedException, which defaults to an 86400 second suspension, while Cloudflare-triggered bans combine an 86400 second access-denied timer with a separate 1296000 second (15-day) captcha timer.

Confirm the ban in logs:

Wait out the suspension or shorten it by editing suspended_times as shown earlier, though shortening it too much risks a longer, harder ban.

Reduce request concentration by adding more engines and enabling the limiter so requests spread out instead of hitting one origin repeatedly.

A single undersized VPS often struggles here because a full ban takes that engine offline for you until the suspension clears, with no way to speed it up. This is where infrastructure matters; running your instance on a Linux VPS with more space and better network gives you room to spread requests across engines and recover faster.

If your search instance is getting too much traffic, moving it to a strong Linux VPS with more resources is worth doing before you keep tuning settings on hardware that's already maxed out.

You can keep these on hand whenever something looks wrong, which covers every symptom in this SearXNG troubleshooting guide:

Running docker compose ps first tells you if a container silently died, which is often the real cause behind random search failures.

A stable public instance isn't about surviving restarts; it's about staying responsive when real users or apps depend on it every hour. Every fix in this SearXNG troubleshooting guide, the limiter, a working Valkey connection, correct suspension timers, enough engines, and the right output formats, works together, not in isolation.

Note: If you're pairing SearXNG with automation, the n8n setup on a VPS tutorial shows how to connect a search backend to a workflow engine.

Fixing SearXNG under real traffic depends on a short list of commands and settings, including enabling the limiter with a working Valkey connection, adjusting suspension timers per error type, disabling engines that stay broken, and allowing the right JSON formats.

Follow each step in this SearXNG troubleshooting guide in order, check logs after every change, and most instances stop breaking within a day or two.

We hope you enjoy this SearXNG troubleshooting guide. For full error definitions and default suspension timers, you can check the official SearXNG exceptions documentation.