open-webui · Classic298 · Dec 31, 2025 · Dec 31, 2025
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
-Original file line number
+Diff line change
@@ Expand Up @@
     :::
+    :::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
@@ Expand Down @@