assafelovic/gpt-researcher · error · ValueError

RETRIEVER_ENDPOINT environment variable not set

Error message

RETRIEVER_ENDPOINT environment variable not set

What it means

ValueError raised by the custom retriever's __init__ when the RETRIEVER_ENDPOINT environment variable is unset/empty. The custom retriever delegates all fetching to an external HTTP endpoint, so without it there is nothing to query.

Source

Thrown at gpt_researcher/retrievers/custom/custom.py:18

from typing import Any, Dict, List
import requests
import os


class CustomRetriever:
    """
    Custom API Retriever
    """

    # The documented contract is list[{url, raw_content}] -- the caller's own
    # endpoint supplies the content.
    requires_scraping = False

    def __init__(self, query: str, query_domains=None):
        self.endpoint = os.getenv('RETRIEVER_ENDPOINT')
        if not self.endpoint:
            raise ValueError("RETRIEVER_ENDPOINT environment variable not set")

        self.params = self._populate_params()
        self.query = query

    def _populate_params(self) -> Dict[str, Any]:
        """
        Populates parameters from environment variables prefixed with 'RETRIEVER_ARG_'
        """
        return {
            key[len('RETRIEVER_ARG_'):].lower(): value
            for key, value in os.environ.items()
            if key.startswith('RETRIEVER_ARG_')
        }

    def search(self, max_results: int = 5) -> List[Dict[str, Any]]:
        """
        Performs the search using the custom retriever endpoint.

View on GitHub (pinned to 6f998577d5)

Solutions

1. Set RETRIEVER_ENDPOINT to your retrieval service's URL (e.g. http://localhost:8000/retrieve).
2. Add it to .env and verify it's loaded before the retriever is created.
3. Double-check spelling (RETRIEVER_ENDPOINT, not RETRIEVER_URL) in compose/k8s files.

Example fix

# before
r = Custom(query="...")  # raises ValueError

# after
import os
os.environ.setdefault("RETRIEVER_ENDPOINT", "http://localhost:8000/retrieve")
r = Custom(query="...")

import os
if not os.getenv("RETRIEVER_ENDPOINT"):
    raise SystemExit("Set RETRIEVER_ENDPOINT to your retrieval service URL")

null

try:
    r = Custom(query)
except ValueError as e:
    if "RETRIEVER_ENDPOINT" in str(e):
        raise SystemExit(str(e))
    raise

When it happens

Trigger: Instantiating the custom retriever with os.getenv('RETRIEVER_ENDPOINT') returning None or "".

Common situations: Configuring retriever="custom" without providing the endpoint var, .env not loaded, or a typo in the variable name in deployment configs.

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

• Bing API key not found. Please set the BING_API_KEY environm
• Brave Search API key not found. Please set the BRAVE_API_KEY
• Exa API key not found. Please set the EXA_API_KEY environmen
• GetXAPI API key not found. Please set the GETXAPI_API_KEY en
• Google API key not found. Please set the GOOGLE_API_KEY envi

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