BerriAI/litellm · critical · ValueError

GEMINI_API_KEY is required for Google AI Studio file operati

Error message

GEMINI_API_KEY is required for Google AI Studio file operations

What it means

For Gemini Files API (Google AI Studio file upload), validate_environment() resolves the API key via self.get_api_key() (explicit argument then GOOGLE_API_KEY/GEMINI_API_KEY). If none is found it raises this ValueError — file upload/download calls are authenticated with x-goog-api-key and cannot proceed anonymously.

Source

Thrown at litellm/llms/gemini/files/transformation.py:58

        return LlmProviders.GEMINI

    def validate_environment(
        self,
        headers: dict[Any, Any],
        model: str,
        messages: list[AllMessageValues],
        optional_params: dict[Any, Any],
        litellm_params: dict[Any, Any],
        api_key: str | None = None,
        api_base: str | None = None,
    ) -> dict[Any, Any]:
        """
        Validate environment and add Gemini API key to headers.
        Google AI Studio uses x-goog-api-key header for authentication.
        """
        resolved_api_key: Final = self.get_api_key(api_key)
        if not resolved_api_key:
            raise ValueError("GEMINI_API_KEY is required for Google AI Studio file operations")

        headers["x-goog-api-key"] = resolved_api_key
        return headers

    def get_complete_url(
        self,
        api_base: str | None,
        api_key: str | None,
        model: str,
        optional_params: dict,
        litellm_params: dict,
        stream: bool | None = None,
    ) -> str:
        """
        OPTIONAL

        Get the complete url for the request

View on GitHub (pinned to 6c2dcb801b)

Solutions

Export GOOGLE_API_KEY or GEMINI_API_KEY in the process performing file operations.
Or pass api_key explicitly to the file-creation call / litellm_params.
Verify the variable is non-empty in the exact runtime (container, worker, notebook) that executes the upload.

Example fix

# before
file_obj = litellm.create_file(model="gemini/", file=open("audio.mp3", "rb"), purpose="user_data")  # no key -> ValueError

# after
os.environ["GOOGLE_API_KEY"] = "AIza..."
file_obj = litellm.create_file(model="gemini/", file=open("audio.mp3", "rb"), purpose="user_data")

Defensive patterns

Strategy: validation

Validate before calling

import os

def assert_gemini_files_ready() -> None:
    if not (os.getenv("GOOGLE_API_KEY") or os.getenv("GEMINI_API_KEY")):
        raise RuntimeError("Gemini file operations require GOOGLE_API_KEY/GEMINI_API_KEY")

Try / catch

try:
    litellm.create_file(model="gemini/", file=f, purpose="user_data")
except ValueError as e:
    if "GEMINI_API_KEY is required" in str(e):
        raise RuntimeError("Configure Gemini credentials for file uploads") from e
    raise

Prevention

Run one shared credentials bootstrap for all Gemini features (chat, files, agents).
Pass the key via litellm_params/api_key in server contexts where env vars are unreliable.
Add a tiny file-upload smoke test to CI for every provider you use files with.

When it happens

Trigger: Calling litellm.create_file(...) / file operations for gemini with no api_key argument and no GOOGLE_API_KEY or GEMINI_API_KEY in the environment.

Common situations: Adding multimodal file uploads to an app whose chat path used a different provider; key configured only for the completion client via Router but file calls run through module-level functions; empty-string env var.

Related errors

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