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.

Why SearXNG Breaks Under Real Traffic

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.

Fix Rate Limits with the Limiter

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:

Step 1. Enable the limiter

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

server:
  limiter: true

Step 2. Point it to a Valkey database (Redis-compatible)

Still in settings.yml:

valkey:
  url: valkey://localhost:6379/0

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.

Step 3. Set trusted proxy headers

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.

Step 4. Tune SearXNG Toml File

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

[botdetection.ip_limit]
link_token = true

[botdetection.ip_lists]
pass_ip = ["203.0.113.10"]
block_ip = ["198.51.100.5"]

Step 5. Restart the container

To apply the changes, restart the container:

docker compose restart searxng

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.

Fix Captcha Walls from Search Engines

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:

Step 1. Confirm it’s a captcha, not something else

Check the logs to verify it’s a captcha:

docker compose logs -f searxng | grep -i captcha

Step 2. Adjust suspension timers if needed

In settings.yml, under search::

search:
  suspended_times:
    SearxEngineCaptcha: 86400
    recaptcha_SearxEngineCaptcha: 604800
    cf_SearxEngineCaptcha: 1296000

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.

Step 3. Reduce trigger frequency

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.

Fix Redis and Valkey Connection Errors

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:

docker compose ps

Look for the redis or valkey service status. If it’s not “Up,” check its logs:

docker compose logs redis

Test the connection directly from inside the SearXNG container:

docker compose exec searxng sh
redis-cli -u valkey://localhost:6379/0 ping

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:

valkey:
  url: valkey://redis:6379/0

Recreate the network if it’s missing entirely:

docker network create searxng
docker compose up -d

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.

Fix Broken and Missing Search Engines

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:

Step 1. Identify which engine is failing

Use the command below to find which engine is failing:

docker compose logs searxng | grep -i "SearxEngine"

Step 2. Match the error to its type

Each exception maps to a different cause:

Exception	Meaning	Default suspension
SearxEngineResponseException	Parser broke, can’t read results	ban_time_on_fail
SearxEngineAPIException	The engine’s own server returned an error	ban_time_on_fail
SearxEngineAccessDeniedException	The engine is actively blocking you	86400 sec
SearxEngineTooManyRequestsException	HTTP 429, too many requests	3600 sec

Step 3. Update SearXNG

Parser fixes for broken engines ship regularly:

cd /usr/local/searxng
git pull origin master
docker compose restart searxng

Step 4. Disable engines that stay broken

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

engines:
  - name: presearch
    disabled: true

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.

Fix Broken JSON Response Format

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:

search:
  formats:
    - html
    - json

Restart to apply it:

docker compose restart searxng

Test the API call:

curl "http://localhost:8080/search?q=test&format=json"

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.

Fix Outbound Bans and IP-Level Blocks

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:

docker compose logs searxng | grep -i "access denied"

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.

SearXNG Troubleshooting Guide | Quick Diagnostic Commands

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

docker compose ps
docker compose logs -f searxng
docker compose logs -f redis
docker compose exec searxng sh
docker stats
docker compose restart searxng

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

Keeping SearXNG Stable Under Load

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.

Conclusion

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.

FAQs