BerriAI/litellm · error · ValueError

GEMINI_API_KEY or GOOGLE_API_KEY is required

Error message

GEMINI_API_KEY or GOOGLE_API_KEY is required

What it means

Raised in the Gemini vector-store search request transform when no API key is found: it checks litellm_params['api_key'] then falls back to GeminiModelInfo.get_api_key() (GEMINI_API_KEY / GOOGLE_API_KEY env). File Search grounds generateContent calls against a file search store, which requires a Google API key, so the request is aborted with ValueError.

Source

Thrown at litellm/llms/gemini/vector_stores/transformation.py:132

    ) -> tuple[str, dict]:
        """
        Transform search request to Gemini's generateContent format.

        Gemini File Search works by calling generateContent with a file_search tool.
        """
        # Convert query list to single string if needed
        if isinstance(query, list):
            query = " ".join(query)

        # Get model from litellm_params or use default
        # Note: File Search requires gemini-2.5-flash or later
        model = litellm_params.get("model") or "gemini-2.5-flash"
        if model and model.startswith("gemini/"):
            model = model.replace("gemini/", "")

        api_key: Final = litellm_params.get("api_key") or GeminiModelInfo.get_api_key()
        if not api_key:
            raise ValueError("GEMINI_API_KEY or GOOGLE_API_KEY is required")
        url: Final = f"{api_base}/models/{model}:generateContent"

        # Build file_search tool configuration (using snake_case as per Gemini docs)
        file_search_config: Final[dict[str, Any]] = {"file_search_store_names": [vector_store_id]}

        # Add metadata filter if provided
        metadata_filter: Final = vector_store_search_optional_params.get("filters")
        if metadata_filter:
            # Convert to Gemini filter syntax if it's a dict
            if isinstance(metadata_filter, dict):
                # Simple conversion - may need more sophisticated mapping
                filter_parts: Final = []
                for key, value in metadata_filter.items():
                    if isinstance(value, str):
                        filter_parts.append(f'{key} = "{value}"')
                    else:
                        filter_parts.append(f"{key} = {value}")
                file_search_config["metadata_filter"] = " AND ".join(filter_parts)

View on GitHub (pinned to 6c2dcb801b)

Solutions

  1. Pass api_key in litellm_params: {'api_key': 'AIza...'} on the search call.
  2. Export GEMINI_API_KEY or GOOGLE_API_KEY in the calling process.
  3. Ensure the value is non-empty (an empty string also fails the truthiness check).

Example fix

# before
results = litellm.vector_store_search(vector_store_id=vs_id, query='hello', litellm_params={'model': 'gemini-2.5-flash'})

# after
import os
results = litellm.vector_store_search(
    vector_store_id=vs_id,
    query='hello',
    litellm_params={'model': 'gemini-2.5-flash', 'api_key': os.environ['GEMINI_API_KEY']},
)
Defensive patterns

Strategy: validation

Validate before calling

import os

def has_gemini_key(litellm_params=None) -> bool:
    return bool(
        (litellm_params or {}).get("api_key")
        or os.environ.get("GEMINI_API_KEY")
        or os.environ.get("GOOGLE_API_KEY")
    )

if not has_gemini_key(params):
    raise ConfigError("Gemini key required for File Search")

Try / catch

try:
    results = litellm.vector_store_search(vector_store_id=vs, query=q, litellm_params=params)
except ValueError as e:
    if "GEMINI_API_KEY or GOOGLE_API_KEY is required" in str(e):
        raise ConfigError("Missing Gemini key for File Search") from e
    raise

Prevention

When it happens

Trigger: Calling litellm.vector_store_search (Gemini File Search) with model gemini-2.5-flash and no api_key in litellm_params while GEMINI_API_KEY/GOOGLE_API_KEY are unset in the environment.

Common situations: Env vars configured for the LLM proxy but not the worker doing file search; key rotation leaving stale empty-string env values; CI pipelines lacking secrets.

Related errors

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