BerriAI/litellm · error · ValueError

BRAVE_API_KEY is not set. Set `BRAVE_API_KEY` environment…

Error message

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

What it means

Brave search transformation resolves the API key via resolve_server_api_key (caller api_key argument or BRAVE_API_KEY env var). If nothing resolves, it raises this plain ValueError before any HTTP call. Brave requires the X-Subscription-Token header, which cannot be built without the key.

Solutions

export BRAVE_API_KEY=<your key> in the process running LiteLLM.
Or pass the key explicitly via the api_key argument for the search call/config.
For the proxy, add BRAVE_API_KEY to the proxy environment (docker env, .env loaded by proxy).
Confirm with a quick check that the var is visible: python -c "import os; print(bool(os.environ.get('BRAVE_API_KEY')))".

Example fix

# before
# BRAVE_API_KEY not set anywhere
results = litellm.web_search_provider(..., provider="brave")

# after
os.environ["BRAVE_API_KEY"] = "BSA..."
results = litellm.web_search_provider(..., provider="brave")

Defensive patterns

Strategy: validation

Validate before calling

import os

def brave_key_available() -> bool:
    return bool(os.environ.get("BRAVE_API_KEY"))

Try / catch

try:
    results = brave_search(query)
except ValueError as e:
    if "BRAVE_API_KEY" in str(e):
        raise RuntimeError("Search unavailable: BRAVE_API_KEY not configured") from e
    raise

Prevention

Check the env var at app startup, not per request.
Inject the key via your deployment platform's secret mechanism so all processes see it.

When it happens

Trigger: Invoking litellm's web search with the Brave provider without passing api_key and without BRAVE_API_KEY in the environment; typo'd env var name; key set in a different shell/process than the one running litellm (proxy, CI, docker).

Common situations: Deploying the LiteLLM proxy without forwarding BRAVE_API_KEY into the container; local shell exports not visible to a systemd service; rotating the key and forgetting to update the env; CI pipelines missing secrets.

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

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

Appendix: 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 77b7c6c40c)