BerriAI/litellm · critical · ValueError

BRAVE_API_KEY is not set. Set `BRAVE_API_KEY` environment va

Error message

BRAVE_API_KEY is not set. Set `BRAVE_API_KEY` environment variable.

What it means

For the Brave search provider, validate_environment resolves the API key via resolve_server_api_key (caller api_key, then BRAVE_API_KEY env / server-side config). If resolution returns nothing, this ValueError is raised before any request is sent. It is purely a configuration error, not a Brave-side rejection.

Source

Thrown at litellm/llms/brave/search/transformation.py:128

        self,
        headers: dict,
        api_key: str | None = None,
        api_base: str | None = None,
        **kwargs,
    ) -> dict:
        """
        Validate environment and return headers.
        """
        api_key = self.resolve_server_api_key(
            caller_api_key=api_key,
            caller_api_base=api_base,
            key_env_vars=("BRAVE_API_KEY",),
            base_env_var="BRAVE_API_BASE",
            default_api_base=self.BRAVE_API_BASE,
        )

        if not api_key:
            raise ValueError("BRAVE_API_KEY is not set. Set `BRAVE_API_KEY` environment variable.")

        headers["X-Subscription-Token"] = api_key
        headers["Accept"] = "application/json"
        headers["Accept-Encoding"] = "gzip"
        headers["Content-Type"] = "application/json"

        return headers

    def get_complete_url(
        self,
        api_base: str | None,
        optional_params: dict,
        data: dict | list[dict] | None = None,
        **kwargs,
    ) -> str:
        """
        Get complete URL for Search endpoint with query parameters.

View on GitHub (pinned to 6c2dcb801b)

Solutions

export BRAVE_API_KEY=<key> (get one from the Brave Search API dashboard) in the process running litellm.
Or pass api_key explicitly in the call.
On litellm proxy, set it in the environment of the proxy process or its env_config, then restart.
Verify: echo ${BRAVE_API_KEY:+set} inside the same runtime.

Example fix

# before
litellm.web_search(...)  # or proxy config without the key

# after
export BRAVE_API_KEY=BSAxxx
# or
response = litellm.completion(..., web_search_options=...)  # with BRAVE_API_KEY exported

Defensive patterns

Strategy: validation

Validate before calling

import os

if not os.getenv("BRAVE_API_KEY"):
    raise RuntimeError("BRAVE_API_KEY must be set before enabling Brave search")

Try / catch

try:
    result = brave_search_call(...)
except ValueError as e:
    if "BRAVE_API_KEY is not set" in str(e):
        raise SystemExit("Configuration error: set BRAVE_API_KEY") from e  # fail fast, no retry
    raise

Prevention

Add a boot-time check for BRAVE_API_KEY in services using Brave search.
Store provider keys in a secrets manager and inject at deploy time.
Distinguish config errors (ValueError pre-request) from API errors in monitoring.

When it happens

Trigger: Invoking litellm's Brave search/web search with no api_key argument while BRAVE_API_KEY is unset in both the caller's environment and the litellm proxy server's secret store.

Common situations: New deployments missing the env var; litellm proxy users who set the key on the client but the proxy requires it server-side; .env not loaded in serverless/CI; key configured under a different provider's name.

Related errors

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/5504064a8b9c7a4b. Report an issue: GitHub.