assafelovic/gpt-researcher · error · Exception

Brave Search API key not found. Please set the BRAVE_API_KEY

Error message

Brave Search API key not found. Please set the BRAVE_API_KEY environment variable.

What it means

Exception raised by the Brave retriever when the BRAVE_API_KEY environment variable is not set; the os.environ lookup fails and the handler re-raises with this explanatory message. The Brave Search API requires this key for every request.

Source

Thrown at gpt_researcher/retrievers/brave/brave.py:35

        Initializes the BraveSearch object
        Args:
            query:
        """
        self.query = query
        self.query_domains = query_domains or None
        self.api_key = self.get_api_key()
        self.logger = logging.getLogger(__name__)

    def get_api_key(self):
        """
        Gets the Brave Search API key
        Returns:

        """
        try:
            api_key = os.environ["BRAVE_API_KEY"]
        except Exception:
            raise Exception(
                "Brave Search API key not found. Please set the BRAVE_API_KEY environment variable."
            )
        return api_key

    def search(self, max_results=7) -> list[dict[str, str]]:
        """
        Searches the query
        Returns:

        """
        print("Searching with query {0}...".format(self.query))
        """Useful for general internet search queries using the Brave Search API."""

        url = "https://api.search.brave.com/res/v1/web/search"
        headers = {
            "X-Subscription-Token": self.api_key,
            "Accept": "application/json",
            "Accept-Encoding": "gzip",

View on GitHub (pinned to 6f998577d5)

Solutions

export BRAVE_API_KEY=<key> (get one at api.search.brave.com).
Put BRAVE_API_KEY in .env and confirm it loads before creating the retriever.
Inject the variable in your deployment environment (Docker -e, k8s secret, CI variable).

Example fix

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

# after
import os
if not os.environ.get("BRAVE_API_KEY"):
    raise SystemExit("BRAVE_API_KEY missing")
retriever = Brave(query="...")

Defensive patterns

Strategy: validation

Validate before calling

import os
if not os.environ.get("BRAVE_API_KEY"):
    raise SystemExit("BRAVE_API_KEY missing")

Type guard

null

Try / catch

try:
    retriever = Brave(query)
except Exception as e:
    if "BRAVE_API_KEY" in str(e):
        logger.error(e); sys.exit(1)
    raise

Prevention

Check env vars at startup.
Inject secrets via the platform's secret manager.
Keep a startup preflight that validates all configured retrievers' keys.

When it happens

Trigger: Constructing the Brave retriever (its __init__ calls get_api_key()) without BRAVE_API_KEY present in the environment.

Common situations: Key not exported, .env not loaded in the runtime, or deploying to a server/container where the variable was never injected.

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/fde6e26222520095. Report an issue: GitHub.