BerriAI/litellm · error · ValueError

An API key is required to resolve Gemini file references (fi

Error message

An API key is required to resolve Gemini file references (files/...). Pass api_key= or set GEMINI_API_KEY.

What it means

Gemini embed-with-files guard: the input contains files/... references that must be resolved via the Files API, but no api_key (argument or GEMINI_API_KEY) is available to authorize those resolution calls.

Source

Thrown at litellm/llms/vertex_ai/gemini_embeddings/batch_embed_content_handler.py:224

                logging_obj=logging_obj,
            )

        ### TRANSFORMATION (sync path) ###
        request_data: Any
        if use_embed_content:
            resolved_files = {}
            if api_key:
                resolved_files = self._resolve_file_references(input=input, api_key=api_key, sync_handler=sync_handler)
            request_data = transform_openai_input_gemini_embed_content(
                input=input,
                model=model,
                optional_params=optional_params,
                resolved_files=resolved_files,
            )
        else:
            flat_elements, has_file_refs = self._flatten_and_detect_file_refs(input)
            if has_file_refs and not api_key:
                raise ValueError(
                    "An API key is required to resolve Gemini file references (files/...). "
                    "Pass api_key= or set GEMINI_API_KEY."
                )
            resolved_files = {}
            if api_key and has_file_refs:
                resolved_files = self._resolve_file_references(
                    input=flat_elements, api_key=api_key, sync_handler=sync_handler
                )
            request_data = transform_openai_input_gemini_content(
                input=input,
                model=model,
                optional_params=optional_params,
                resolved_files=resolved_files,
            )

        ## LOGGING
        logging_obj.pre_call(
            input=input,

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Pass api_key= or set GEMINI_API_KEY to resolve files/... references.

Example fix

os.environ["GEMINI_API_KEY"] = "<key>"

When it happens

Trigger: Triggered when a Gemini file reference (files/...) is used without an API key: api_key not passed and GEMINI_API_KEY unset.

Common situations: See trigger scenarios.

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