BerriAI/litellm · critical · ValueError

Google API key is required. Set GOOGLE_API_KEY or GEMINI_API

Error message

Google API key is required. Set GOOGLE_API_KEY or GEMINI_API_KEY, or pass api_key.

What it means

When building headers for a Gemini agents request, litellm resolves the key via GeminiModelInfo.get_api_key(): an explicit litellm_params api_key first, then GOOGLE_API_KEY, then GEMINI_API_KEY. If nothing resolves it raises this ValueError naming all three ways to supply the key; the request never leaves the process.

Source

Thrown at litellm/llms/gemini/agents/transformation.py:116

    ) -> dict[str, str]:
        headers = dict(headers)
        headers["Content-Type"] = "application/json"
        explicit_api_key: Final = litellm_params.get("api_key")
        # SECURITY: when the caller overrides ``api_base``, refuse to fall back
        # to the process-wide GOOGLE_API_KEY / GEMINI_API_KEY env vars. Otherwise
        # an authenticated proxy user could set ``api_base`` to an attacker-
        # controlled host and have the proxy ship its shared Gemini key in the
        # ``x-goog-api-key`` header.
        if litellm_params.get("api_base") and not explicit_api_key:
            raise ValueError(
                "When overriding api_base for Gemini agents, you must also "
                "supply an explicit api_key. Falling back to GOOGLE_API_KEY / "
                "GEMINI_API_KEY env vars with a custom api_base is refused "
                "to prevent leaking the shared provider key to arbitrary hosts."
            )
        api_key: Final = GeminiModelInfo.get_api_key(explicit_api_key)
        if not api_key:
            raise ValueError("Google API key is required. Set GOOGLE_API_KEY or GEMINI_API_KEY, or pass api_key.")
        headers["x-goog-api-key"] = api_key
        return headers

    def _raise_for_status(self, raw_response: httpx.Response) -> None:
        if not (200 <= raw_response.status_code < 300):
            raise GeminiError(
                message=raw_response.text,
                status_code=raw_response.status_code,
                headers=dict(raw_response.headers),
            )

    # ------------------------------------------------------------------ #
    # CREATE                                                               #
    # ------------------------------------------------------------------ #

    def transform_create_request(
        self,
        name: str,

View on GitHub (pinned to 6c2dcb801b)

Solutions

Export GOOGLE_API_KEY (or GEMINI_API_KEY) with an AI Studio key (AIza...).
Or pass api_key explicitly on the call / in litellm_params for the agent request.
In containers, confirm the variable is baked into the image or passed with -e; check for empty-string values, which also fail the truthiness check.

Example fix

# before
os.environ.pop("GOOGLE_API_KEY", None)
litellm.agent_create(...)  # or agents completion path -> ValueError

# after
os.environ["GOOGLE_API_KEY"] = "AIza..."
litellm.agent_create(...)

Defensive patterns

Strategy: validation

Validate before calling

import os

def resolve_gemini_key() -> str:
    key = os.getenv("GOOGLE_API_KEY") or os.getenv("GEMINI_API_KEY")
    if not key:
        raise RuntimeError("Set GOOGLE_API_KEY or GEMINI_API_KEY for Gemini agents")
    return key

Try / catch

try:
    litellm.agent_create(...)
except ValueError as e:
    if "Google API key is required" in str(e):
        raise RuntimeError("Gemini credentials missing in this environment") from e
    raise

Prevention

Check both GOOGLE_API_KEY and GEMINI_API_KEY in startup health checks for services using Gemini agents.
Pass api_key explicitly via litellm_params in multi-key setups.
Note that GOOGLE_APPLICATION_CREDENTIALS (ADC) does not satisfy this check — an AI Studio API key is required.

When it happens

Trigger: Invoking Gemini agents (create/agent endpoints) with none of api_key param, GOOGLE_API_KEY, or GEMINI_API_KEY set — e.g. fresh environment, or the variables live only in a different shell/deployment.

Common situations: New Gemini integration before any key is configured; env var present in dev shell but missing in Docker/CI; key stored under a different name (GOOGLE_API_KEY vs GEMINI_API_KEY confusion, or a GOOGLE_APPLICATION_CREDENTIALS file which is not consulted here).

Related errors

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