assafelovic/gpt-researcher · error · Exception

SearxNG URL not found. Please set the SEARX_URL environment

Error message

SearxNG URL not found. Please set the SEARX_URL environment variable. You can find public instances at https://searx.space/

What it means

Exception raised by the SearxNG retriever when the SEARX_URL environment variable is unset (KeyError caught and re-raised). SearxNG is self-hosted/community-hosted metasearch, so the instance URL must be configured explicitly.

Source

Thrown at gpt_researcher/retrievers/searx/searx.py:55

            query: Search query string
        """
        self.query = query
        self.query_domains = query_domains or None
        self.base_url = self.get_searxng_url()

    def get_searxng_url(self) -> str:
        """
        Gets the SearxNG instance URL from environment variables
        Returns:
            str: Base URL of SearxNG instance
        """
        try:
            base_url = os.environ["SEARX_URL"]
            if not base_url.endswith('/'):
                base_url += '/'
            return base_url
        except KeyError:
            raise Exception(
                "SearxNG URL not found. Please set the SEARX_URL environment variable. "
                "You can find public instances at https://searx.space/"
            )

    def search(self, max_results: int = 10) -> List[Dict[str, str]]:
        """
        Searches the query using SearxNG API
        Args:
            max_results: Maximum number of results to return
        Returns:
            List of dictionaries containing search results
        """
        search_url = urljoin(self.base_url, "search")
        # TODO: Add support for query domains
        params = {
            # The search query.
            'q': self.query,
            # Output format of results. Format needs to be activated in searxng config.

View on GitHub (pinned to 6f998577d5)

Solutions

export SEARX_URL=https://your-searx-instance (public instances at https://searx.space/).
If self-hosting, enable JSON format in settings.yml (search.formats: [html, json]).
Add SEARX_URL to .env and verify it loads before retriever creation.

Example fix

# before
retriever = SearxNG(query="...")

# after
export SEARX_URL=http://localhost:8888
# then
retriever = SearxNG(query="...")

Defensive patterns

Strategy: validation

Validate before calling

import os
from urllib.parse import urlparse
url = os.environ.get("SEARX_URL")
if not url or not urlparse(url).scheme:
    raise SystemExit("Set SEARX_URL to a SearxNG instance (https://searx.space/)")

Type guard

null

Try / catch

try:
    retriever = SearxNG(query)
except Exception as e:
    if "SEARX_URL" in str(e):
        sys.exit(str(e))
    raise

Prevention

Set SEARX_URL in .env; prefer a self-hosted instance you control.
Confirm the instance allows format=json before relying on it.
Preflight the URL at startup.

When it happens

Trigger: Constructing the SearxNG retriever; __init__ calls get_searxng_url(), which raises when SEARX_URL is missing. A trailing slash is appended automatically when present.

Common situations: No SEARX_URL set for a self-hosted instance, .env not loaded, URL pointing to an instance with JSON output disabled, or var name typoed.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of assafelovic/gpt-researcher@6f998577d5 (2026-08-28). Data as JSON: /api/errors/a0b116c5695aa32c. Report an issue: GitHub.