From 0733a99dfb04bffe02c7d613b95df309cc30e0cc Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Wed, 31 Dec 2025 12:40:26 +0100 Subject: [PATCH] web search troubleshooting --- docs/features/index.mdx | 2 +- docs/features/web-search/bing.md | 6 + docs/features/web-search/brave.md | 6 + docs/features/web-search/ddgs.mdx | 6 + docs/features/web-search/exa.md | 6 + docs/features/web-search/external.md | 6 + docs/features/web-search/google-pse.md | 6 + docs/features/web-search/jina.md | 6 + docs/features/web-search/kagi.md | 6 + docs/features/web-search/mojeek.md | 6 + docs/features/web-search/ollama-cloud.mdx | 6 + docs/features/web-search/perplexity.mdx | 6 + .../features/web-search/perplexity_search.mdx | 6 + docs/features/web-search/searchapi.md | 6 + docs/features/web-search/searxng.md | 6 + docs/features/web-search/serpapi.md | 6 + docs/features/web-search/serper.md | 6 + docs/features/web-search/serply.md | 6 + docs/features/web-search/serpstack.md | 6 + docs/features/web-search/tavily.md | 6 + docs/features/web-search/yacy.md | 6 + docs/troubleshooting/web-search.mdx | 114 ++++++++++++++++++ 22 files changed, 235 insertions(+), 1 deletion(-) create mode 100644 docs/troubleshooting/web-search.mdx diff --git a/docs/features/index.mdx b/docs/features/index.mdx index 40417975..a24bf056 100644 --- a/docs/features/index.mdx +++ b/docs/features/index.mdx @@ -380,7 +380,7 @@ import { TopBanners } from "@site/src/components/TopBanners"; - 🔑 **Simplified API Key Management**: Easily generate and manage secret keys to leverage Open WebUI with OpenAI libraries, streamlining integration and development. -- 🌐 **HTTP/S Proxy Support**: Configure network settings easily using the `http_proxy` or `https_proxy` environment variable. These variables, if set, should contain the URLs for HTTP and HTTPS proxies, respectively. +- 🌐 **HTTP/S Proxy Support**: Configure network settings easily using the `http_proxy` or `https_proxy` environment variable. These variables, if set, should contain the URLs for HTTP and HTTPS proxies, respectively. For web search content fetching behind a proxy, enable **Trust Proxy Environment** in Admin Panel > Settings > Web Search (or set `WEB_SEARCH_TRUST_ENV=True`). - 🌐🔗 **External Ollama Server Connectivity**: Seamlessly link to an external Ollama server hosted on a different address by configuring the environment variable. diff --git a/docs/features/web-search/bing.md b/docs/features/web-search/bing.md index 39ee125d..094d61ed 100644 --- a/docs/features/web-search/bing.md +++ b/docs/features/web-search/bing.md @@ -15,6 +15,12 @@ For a comprehensive list of all environment variables related to Web Search (inc ::: +:::tip Troubleshooting + +Having issues with web search? Check out the [Web Search Troubleshooting Guide](../../troubleshooting/web-search) for solutions to common problems like proxy configuration, connection timeouts, and empty content. + +::: + :::warning Bing Search APIs will be retired on 11th August 2025. New deployments are not supported. diff --git a/docs/features/web-search/brave.md b/docs/features/web-search/brave.md index e97a653c..be38e57f 100644 --- a/docs/features/web-search/brave.md +++ b/docs/features/web-search/brave.md @@ -15,6 +15,12 @@ For a comprehensive list of all environment variables related to Web Search (inc ::: +:::tip Troubleshooting + +Having issues with web search? Check out the [Web Search Troubleshooting Guide](../../troubleshooting/web-search) for solutions to common problems like proxy configuration, connection timeouts, and empty content. + +::: + ## Brave API ### Docker Compose Setup diff --git a/docs/features/web-search/ddgs.mdx b/docs/features/web-search/ddgs.mdx index 9b58c1db..d0d4743a 100644 --- a/docs/features/web-search/ddgs.mdx +++ b/docs/features/web-search/ddgs.mdx @@ -15,6 +15,12 @@ For a comprehensive list of all environment variables related to Web Search (inc ::: +:::tip Troubleshooting + +Having issues with web search? Check out the [Web Search Troubleshooting Guide](../../troubleshooting/web-search) for solutions to common problems like proxy configuration, connection timeouts, and empty content. + +::: + ## DDGS (Dux Distributed Global Search - previously DuckDuckGo) ### Setup diff --git a/docs/features/web-search/exa.md b/docs/features/web-search/exa.md index b91ddb19..91fcecc9 100644 --- a/docs/features/web-search/exa.md +++ b/docs/features/web-search/exa.md @@ -15,6 +15,12 @@ For a comprehensive list of all environment variables related to Web Search (inc ::: +:::tip Troubleshooting + +Having issues with web search? Check out the [Web Search Troubleshooting Guide](../../troubleshooting/web-search) for solutions to common problems like proxy configuration, connection timeouts, and empty content. + +::: + # Exa AI Web Search Integration This guide provides instructions on how to integrate [Exa AI](https://exa.ai/), a modern AI-powered search engine, with Open WebUI for web search capabilities. diff --git a/docs/features/web-search/external.md b/docs/features/web-search/external.md index 23a0776a..901f02ef 100644 --- a/docs/features/web-search/external.md +++ b/docs/features/web-search/external.md @@ -15,6 +15,12 @@ For a comprehensive list of all environment variables related to Web Search (inc ::: +:::tip Troubleshooting + +Having issues with web search? Check out the [Web Search Troubleshooting Guide](../../troubleshooting/web-search) for solutions to common problems like proxy configuration, connection timeouts, and empty content. + +::: + ## External Web Search API This option allows you to connect Open WebUI to your own self-hosted web search API endpoint. This is useful if you want to: diff --git a/docs/features/web-search/google-pse.md b/docs/features/web-search/google-pse.md index 656128e9..1edd917b 100644 --- a/docs/features/web-search/google-pse.md +++ b/docs/features/web-search/google-pse.md @@ -15,6 +15,12 @@ For a comprehensive list of all environment variables related to Web Search (inc ::: +:::tip Troubleshooting + +Having issues with web search? Check out the [Web Search Troubleshooting Guide](../../troubleshooting/web-search) for solutions to common problems like proxy configuration, connection timeouts, and empty content. + +::: + ## Google PSE API ### Setup diff --git a/docs/features/web-search/jina.md b/docs/features/web-search/jina.md index a36d4545..728e74a4 100644 --- a/docs/features/web-search/jina.md +++ b/docs/features/web-search/jina.md @@ -15,6 +15,12 @@ For a comprehensive list of all environment variables related to Web Search (inc ::: +:::tip Troubleshooting + +Having issues with web search? Check out the [Web Search Troubleshooting Guide](../../troubleshooting/web-search) for solutions to common problems like proxy configuration, connection timeouts, and empty content. + +::: + # Jina Web Search Integration This guide provides instructions on how to integrate [Jina AI](https://jina.ai/), a powerful AI-driven search foundation, with Open WebUI. The integration uses Jina's `DeepSearch` API to provide web search capabilities. diff --git a/docs/features/web-search/kagi.md b/docs/features/web-search/kagi.md index 1829ee61..c0167fdf 100644 --- a/docs/features/web-search/kagi.md +++ b/docs/features/web-search/kagi.md @@ -14,3 +14,9 @@ This tutorial is a community contribution and is not supported by the Open WebUI For a comprehensive list of all environment variables related to Web Search (including concurrency settings, result counts, and more), please refer to the [Environment Configuration documentation](../../getting-started/env-configuration#web-search). ::: + +:::tip Troubleshooting + +Having issues with web search? Check out the [Web Search Troubleshooting Guide](../../troubleshooting/web-search) for solutions to common problems like proxy configuration, connection timeouts, and empty content. + +::: diff --git a/docs/features/web-search/mojeek.md b/docs/features/web-search/mojeek.md index 79b332f9..e1d2d977 100644 --- a/docs/features/web-search/mojeek.md +++ b/docs/features/web-search/mojeek.md @@ -15,6 +15,12 @@ For a comprehensive list of all environment variables related to Web Search (inc ::: +:::tip Troubleshooting + +Having issues with web search? Check out the [Web Search Troubleshooting Guide](../../troubleshooting/web-search) for solutions to common problems like proxy configuration, connection timeouts, and empty content. + +::: + ## Mojeek Search API ### Setup diff --git a/docs/features/web-search/ollama-cloud.mdx b/docs/features/web-search/ollama-cloud.mdx index 0874daa8..09956d38 100644 --- a/docs/features/web-search/ollama-cloud.mdx +++ b/docs/features/web-search/ollama-cloud.mdx @@ -14,3 +14,9 @@ This tutorial is a community contribution and is not supported by the Open WebUI For a comprehensive list of all environment variables related to Web Search (including concurrency settings, result counts, and more), please refer to the [Environment Configuration documentation](../../getting-started/env-configuration#web-search). ::: + +:::tip Troubleshooting + +Having issues with web search? Check out the [Web Search Troubleshooting Guide](../../troubleshooting/web-search) for solutions to common problems like proxy configuration, connection timeouts, and empty content. + +::: diff --git a/docs/features/web-search/perplexity.mdx b/docs/features/web-search/perplexity.mdx index 5ab89c7a..1969a1b1 100644 --- a/docs/features/web-search/perplexity.mdx +++ b/docs/features/web-search/perplexity.mdx @@ -15,6 +15,12 @@ For a comprehensive list of all environment variables related to Web Search (inc ::: +:::tip Troubleshooting + +Having issues with web search? Check out the [Web Search Troubleshooting Guide](../../troubleshooting/web-search) for solutions to common problems like proxy configuration, connection timeouts, and empty content. + +::: + ## Perplexity API :::info diff --git a/docs/features/web-search/perplexity_search.mdx b/docs/features/web-search/perplexity_search.mdx index b6cec0c0..6989d5da 100644 --- a/docs/features/web-search/perplexity_search.mdx +++ b/docs/features/web-search/perplexity_search.mdx @@ -15,6 +15,12 @@ For a comprehensive list of all environment variables related to Web Search (inc ::: +:::tip Troubleshooting + +Having issues with web search? Check out the [Web Search Troubleshooting Guide](../../troubleshooting/web-search) for solutions to common problems like proxy configuration, connection timeouts, and empty content. + +::: + ## Perplexity Search API :::info diff --git a/docs/features/web-search/searchapi.md b/docs/features/web-search/searchapi.md index 79b5a91f..2d9f3b57 100644 --- a/docs/features/web-search/searchapi.md +++ b/docs/features/web-search/searchapi.md @@ -15,6 +15,12 @@ For a comprehensive list of all environment variables related to Web Search (inc ::: +:::tip Troubleshooting + +Having issues with web search? Check out the [Web Search Troubleshooting Guide](../../troubleshooting/web-search) for solutions to common problems like proxy configuration, connection timeouts, and empty content. + +::: + ## SearchApi API [SearchApi](https://searchapi.io) is a collection of real-time SERP APIs. Any existing or upcoming SERP engine that returns `organic_results` is supported. The default web search engine is `google`, but it can be changed to `bing`, `baidu`, `google_news`, `bing_news`, `google_scholar`, `google_patents`, and others. diff --git a/docs/features/web-search/searxng.md b/docs/features/web-search/searxng.md index 1b49c7e5..03dceee9 100644 --- a/docs/features/web-search/searxng.md +++ b/docs/features/web-search/searxng.md @@ -345,6 +345,12 @@ docker exec -it open-webui curl http://host.docker.internal:8080/search?q=this+i ![SearXNG GUI Configuration](/images/tutorial_searxng_config.png) +:::tip Troubleshooting + +Having issues with web search? Check out the [Web Search Troubleshooting Guide](../../troubleshooting/web-search) for solutions to common problems, including proxy configuration, connection timeouts, and empty content issues. + +::: + ## 5. Using Web Search in a Chat To access Web Search, Click the Integrations button next to the + icon. diff --git a/docs/features/web-search/serpapi.md b/docs/features/web-search/serpapi.md index 46d06a7c..f7aee6fe 100644 --- a/docs/features/web-search/serpapi.md +++ b/docs/features/web-search/serpapi.md @@ -15,6 +15,12 @@ For a comprehensive list of all environment variables related to Web Search (inc ::: +:::tip Troubleshooting + +Having issues with web search? Check out the [Web Search Troubleshooting Guide](../../troubleshooting/web-search) for solutions to common problems like proxy configuration, connection timeouts, and empty content. + +::: + ## SerpApi API [SerpApi](https://serpapi.com/) Scrape Google and other search engines from our fast, easy, and complete API. Any existing or upcoming SERP engine that returns `organic_results` is supported. The default web search engine is `google`, but it can be changed to `bing`, `baidu`, `google_news`, `google_scholar`, `google_patents`, and others. diff --git a/docs/features/web-search/serper.md b/docs/features/web-search/serper.md index 6b2dd8c8..8c4b2b5b 100644 --- a/docs/features/web-search/serper.md +++ b/docs/features/web-search/serper.md @@ -14,3 +14,9 @@ This tutorial is a community contribution and is not supported by the Open WebUI For a comprehensive list of all environment variables related to Web Search (including concurrency settings, result counts, and more), please refer to the [Environment Configuration documentation](../../getting-started/env-configuration#web-search). ::: + +:::tip Troubleshooting + +Having issues with web search? Check out the [Web Search Troubleshooting Guide](../../troubleshooting/web-search) for solutions to common problems like proxy configuration, connection timeouts, and empty content. + +::: diff --git a/docs/features/web-search/serply.md b/docs/features/web-search/serply.md index 9b11d350..6c518e8f 100644 --- a/docs/features/web-search/serply.md +++ b/docs/features/web-search/serply.md @@ -14,3 +14,9 @@ This tutorial is a community contribution and is not supported by the Open WebUI For a comprehensive list of all environment variables related to Web Search (including concurrency settings, result counts, and more), please refer to the [Environment Configuration documentation](../../getting-started/env-configuration#web-search). ::: + +:::tip Troubleshooting + +Having issues with web search? Check out the [Web Search Troubleshooting Guide](../../troubleshooting/web-search) for solutions to common problems like proxy configuration, connection timeouts, and empty content. + +::: diff --git a/docs/features/web-search/serpstack.md b/docs/features/web-search/serpstack.md index 85cebe7b..ee534a3f 100644 --- a/docs/features/web-search/serpstack.md +++ b/docs/features/web-search/serpstack.md @@ -14,3 +14,9 @@ This tutorial is a community contribution and is not supported by the Open WebUI For a comprehensive list of all environment variables related to Web Search (including concurrency settings, result counts, and more), please refer to the [Environment Configuration documentation](../../getting-started/env-configuration#web-search). ::: + +:::tip Troubleshooting + +Having issues with web search? Check out the [Web Search Troubleshooting Guide](../../troubleshooting/web-search) for solutions to common problems like proxy configuration, connection timeouts, and empty content. + +::: diff --git a/docs/features/web-search/tavily.md b/docs/features/web-search/tavily.md index 9838c93c..2b4f2af8 100644 --- a/docs/features/web-search/tavily.md +++ b/docs/features/web-search/tavily.md @@ -15,6 +15,12 @@ For a comprehensive list of all environment variables related to Web Search (inc ::: +:::tip Troubleshooting + +Having issues with web search? Check out the [Web Search Troubleshooting Guide](../../troubleshooting/web-search) for solutions to common problems like proxy configuration, connection timeouts, and empty content. + +::: + ## Overview Integrating Tavily with Open WebUI allows your language model to perform real-time web searches, providing up-to-date and relevant information. This tutorial guides you through configuring Tavily as a web search provider in Open WebUI. diff --git a/docs/features/web-search/yacy.md b/docs/features/web-search/yacy.md index 1def81ca..80b749bd 100644 --- a/docs/features/web-search/yacy.md +++ b/docs/features/web-search/yacy.md @@ -15,6 +15,12 @@ For a comprehensive list of all environment variables related to Web Search (inc ::: +:::tip Troubleshooting + +Having issues with web search? Check out the [Web Search Troubleshooting Guide](../../troubleshooting/web-search) for solutions to common problems like proxy configuration, connection timeouts, and empty content. + +::: + ## Yacy API ### Setup diff --git a/docs/troubleshooting/web-search.mdx b/docs/troubleshooting/web-search.mdx new file mode 100644 index 00000000..2e95e6e0 --- /dev/null +++ b/docs/troubleshooting/web-search.mdx @@ -0,0 +1,114 @@ +--- +sidebar_position: 4 +title: "Troubleshooting Web Search" +--- + +Web Search in Open WebUI allows language models to access real-time information from the internet. When things don't work as expected, this guide will help you diagnose and fix common issues. + +## Common Web Search Issues and How to Fix Them 🛠️ + +### 1. Web Search Fails Behind HTTP Proxy 🌐🔒 + +If you're running Open WebUI behind an HTTP proxy, you might notice that web search queries succeed (e.g., SearXNG returns results), but the subsequent content fetching fails with errors like: + +- `[Errno -3] Temporary failure in name resolution` +- `Connection timeout to host` +- `The content provided is empty` + +This happens because the web content fetcher doesn't use your `http_proxy`/`https_proxy` environment variables by default. + +✅ **Solution:** + +1. Navigate to: **Admin Panel > Settings > Web Search** +2. Enable **Trust Proxy Environment** +3. Save changes + +Alternatively, set the environment variable [`WEB_SEARCH_TRUST_ENV`](../getting-started/env-configuration#web_search_trust_env): + +```bash +WEB_SEARCH_TRUST_ENV=True +``` + +:::info + +This is a **PersistentConfig** variable, meaning it can be set via environment variable on startup OR configured through the Admin Panel UI. Once set in the UI, the database value takes precedence over the environment variable. + +This setting tells Open WebUI's web content loader to respect the proxy settings from your environment variables (`http_proxy`, `https_proxy`). Without this, even if your search engine works through the proxy, fetching content from the returned URLs will fail. + +::: + +--- + +### 2. 403 Forbidden Errors from SearXNG + +If you're using SearXNG and seeing `403 Client Error: Forbidden` in your logs, the JSON format is not enabled. + +✅ **Solution:** + +Edit your SearXNG `settings.yml` and add `json` to the formats list: + +```yaml +search: + formats: + - html + - json +``` + +Restart SearXNG after making this change. + +--- + +### 3. Empty Content or Poor Results + +If web search returns empty content or poor quality results, the issue is often related to context window size or content extraction. + +✅ **Solutions:** + +- **Increase context length**: Web pages often contain 4,000-8,000+ tokens. If your model has a 2048-token limit, you're missing most of the content. Increase to 16384+ tokens in **Admin Panel > Models > Settings > Advanced Parameters** (anything below will be subpar for web content). + +- **Check result count**: Adjust `WEB_SEARCH_RESULT_COUNT` to control how many results are fetched. + +- **Try different loaders**: Configure `WEB_LOADER_ENGINE` to use `playwright` for JavaScript-heavy sites or `firecrawl`/`tavily` for better extraction. + +For more details on context window issues, see the [RAG Troubleshooting Guide](./rag). + +--- + +### 4. Connection Timeouts + +If web searches are timing out: + +✅ **Solutions:** + +- **Reduce concurrent requests**: Set `WEB_SEARCH_CONCURRENT_REQUESTS=1` for sequential execution (required for Brave free tier). + +- **Adjust loader concurrency**: Lower `WEB_LOADER_CONCURRENT_REQUESTS` if fetching many pages simultaneously. + +- **Check network connectivity**: Ensure Open WebUI can reach both the search engine and the result URLs. + +--- + +## Environment Variables Reference + +For a comprehensive list of all web search environment variables, see the [Environment Configuration documentation](../getting-started/env-configuration#web-search). + +Key variables: + +| Variable | Description | +|----------|-------------| +| `WEB_SEARCH_TRUST_ENV` | Enable proxy support for content fetching | +| `WEB_SEARCH_RESULT_COUNT` | Number of search results to fetch | +| `WEB_SEARCH_CONCURRENT_REQUESTS` | Concurrent requests to search engine | +| `WEB_LOADER_CONCURRENT_REQUESTS` | Concurrent page fetches | +| `WEB_LOADER_ENGINE` | Content extraction engine | + +--- + +## Still Having Issues? + +If you're still experiencing problems: + +1. Check the Open WebUI logs for detailed error messages +2. Verify your search engine configuration is correct +3. Test connectivity from the Open WebUI container to your search engine +4. Review all [Web Search environment variables](../getting-started/env-configuration#web-search) for additional configuration options