From 1b2a4111ede2a2c071b0e8be7b0ce0ef09b616fc Mon Sep 17 00:00:00 2001 From: Renato Garita Figueiredo Date: Fri, 25 Sep 2026 14:00:44 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=94=8D=20docs:=20Correct=20How=20SearXNG?= =?UTF-8?q?=20Selects=20Engines=20for=20Web=20Search?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../object_structure/web_search.mdx | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/content/docs/configuration/librechat_yaml/object_structure/web_search.mdx b/content/docs/configuration/librechat_yaml/object_structure/web_search.mdx index f2b4cca24..844f530cd 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/web_search.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/web_search.mdx @@ -175,14 +175,17 @@ webSearch: #### Choosing engines -Engine names must match engines that are enabled on your own instance, and two things follow from that: +Engine names must match engines that exist on your own instance, and a few things follow from that: -- SearXNG ignores an engine it does not recognize instead of reporting an error. A typo, or an engine that is disabled on your instance, shows up as fewer results rather than as a failure. -- The valid names are instance-specific. Check the enabled list at `https://your-instance/config`, which returns JSON including every enabled engine, or open the **Engines** tab of your instance preferences page. +- SearXNG ignores an engine it does not recognize instead of reporting an error, so a typo shows up as fewer results rather than as a failure. The same goes for an engine marked `inactive: true` in the instance settings file, which SearXNG does not load at all. +- An engine that is only disabled on your instance (`disabled: true`) is still queried when you name it. `disabled` takes an engine out of the default selection, and naming it in `engines` overrides that. +- The valid names are instance-specific. `https://your-instance/config` returns JSON listing every engine the instance loaded, each with an `enabled` flag, or open the **Engines** tab of your instance preferences page. The default is `google,bing,duckduckgo`. SearXNG aggregates whatever the selected engines return, so one blocked engine costs you its share of the results rather than the whole response, and a search only comes back empty when every selected engine fails or returns nothing. -DuckDuckGo is the engine in that default set most likely to be blocked, since it serves CAPTCHAs to most self-hosted instances. With only three engines in the set, losing it at the same time as a rate-limited Google or Bing is a common way to end up with no results at all. Setting `engines` explicitly, leaving DuckDuckGo out, and listing more than three engines all reduce that risk. +`engines` adds to the selection rather than replacing it. LibreChat always sends a `categories` parameter as well (see [What these options do not control](#what-these-options-do-not-control)), and when a request carries both, SearXNG queries the listed engines plus every engine enabled for that category on the instance. Leaving an engine out of `engines` therefore does not stop it from being queried. To exclude an engine, disable it in the instance settings file, or mark it `inactive: true` if it also appears in `engines`, as `google`, `bing`, and `duckduckgo` do by default. + +DuckDuckGo is the engine in that default set most likely to be blocked, since it serves CAPTCHAs to most self-hosted instances. Losing it at the same time as a rate-limited Google or Bing is a common way to end up with no results at all. Listing more engines, or enabling more engines for the `general` category on the instance, reduces that risk. Engines that answer quickly and tolerate self-hosted traffic make the best starting set, for example: @@ -204,7 +207,7 @@ Adding more engines widens coverage but also slows every search down, since Sear #### What these options do not control - **Safe search** is not part of this block. It comes from the top-level [`safeSearch`](#safesearch) key and is forwarded to SearXNG as `safesearch`. -- **Result categories** are chosen per query by LibreChat, which maps the search type to `general`, `images`, `videos`, or `news`. They cannot be overridden here. +- **Result categories** are chosen per query by LibreChat, which maps the search type to `general`, `images`, `videos`, or `news`. They cannot be overridden here, and SearXNG adds every engine enabled for the chosen category to the ones in `engines`. - **Page number and result format** are fixed. LibreChat always requests page 1 in JSON format, which is why your instance must have `json` enabled under `formats`. ### tavilyApiKey @@ -758,14 +761,14 @@ A SearXNG search that returns nothing is almost always the request never reachin 1. **The instance is a private address with no `allowedAddresses` entry.** LibreChat blocks loopback and private destinations at connect time, so a self-hosted instance needs its exact `host:port` listed under [`allowedAddresses`](#ssrf-protection-and-private-providers). This blocks the request outright rather than returning an empty result set. 2. **`json` is missing from `formats`.** LibreChat requests results as JSON. If the `formats` section of your instance settings file does not list `json`, the instance answers with an error page and every search comes back empty. This is step 3 of the Docker setup above. -3. **Every selected engine failed.** SearXNG merges the engines that did answer, so an empty response means none of them returned anything. DuckDuckGo is in the default set (`google,bing,duckduckgo`) and serves CAPTCHAs to most self-hosted instances, which leaves only two engines to carry the search. Set `searxngSearchOptions.engines` explicitly, leave DuckDuckGo out, and list a few more engines. -4. **An engine name does not exist on your instance.** SearXNG silently skips engines it does not recognize, so a typo just means fewer results. Compare your list against `https://your-instance/config`. +3. **Every selected engine failed.** SearXNG merges the engines that did answer, so an empty response means none of them returned anything. DuckDuckGo is in the default set (`google,bing,duckduckgo`) and serves CAPTCHAs to most self-hosted instances. List a few more engines in `searxngSearchOptions.engines`, or enable more engines for the `general` category on the instance, since SearXNG queries those as well. The `unresponsive_engines` field of the instance's JSON response names each engine that failed and why. +4. **An engine name does not exist on your instance.** SearXNG silently skips engines it does not recognize or has marked `inactive`, so a typo just means fewer results. Compare your list against `https://your-instance/config`. 5. **The instance is slower than the timeout.** Raise `searxngSearchOptions.timeout` above the default `10000` if your instance queries many engines or sits behind a slow network path. You can reproduce what LibreChat sends by calling the instance directly: ```bash -curl -s "http://localhost:55011/search?q=librechat&format=json&engines=google,bing,startpage" | head -c 500 +curl -s "http://localhost:55011/search?q=librechat&format=json&categories=general&language=all&engines=google,bing,startpage" | head -c 500 ``` This runs from your own machine, so it bypasses LibreChat's connection guard entirely. An empty `results` array here confirms the problem is on the SearXNG side; results here while LibreChat still finds nothing points back at `allowedAddresses`.