crewAIInc/crewAI · error · ValueError

Gemini requires file_uri for FileReference

Error message

Gemini requires file_uri for FileReference

What it means

The Gemini formatter builds a {"fileData": {"mimeType", "fileUri"}} block when the resolved file is a FileReference. Gemini's API requires a concrete file URI (typically a Files API uri like https://generativelanguage.googleapis.com/v1beta/files/...), so an empty file_uri is rejected immediately with ValueError('Gemini requires file_uri for FileReference').

Source

Thrown at lib/crewai-files/src/crewai_files/formatting/gemini.py:35

class GeminiFormatter:
    """Formats resolved files into Gemini content blocks."""

    @staticmethod
    def format_block(resolved: ResolvedFileType) -> dict[str, Any]:
        """Format a resolved file into a Gemini content block.

        Args:
            resolved: Resolved file.

        Returns:
            Content block dict.

        Raises:
            TypeError: If resolved type is not supported.
        """
        if isinstance(resolved, FileReference):
            if not resolved.file_uri:
                raise ValueError("Gemini requires file_uri for FileReference")
            return {
                "fileData": {
                    "mimeType": resolved.content_type,
                    "fileUri": resolved.file_uri,
                }
            }

        if isinstance(resolved, UrlReference):
            return {
                "fileData": {
                    "mimeType": resolved.content_type,
                    "fileUri": resolved.url,
                }
            }

        if isinstance(resolved, InlineBase64):
            return {
                "inlineData": {

View on GitHub (pinned to 754d7323be)

Solutions

1. Upload the file through the Gemini Files API and pass the returned uri in FileReference(file_uri=..., content_type=...).
2. Or skip the reference entirely and pass inline bytes/base64, which the Gemini formatter also supports.
3. Check resolved.file_uri is truthy before calling format_block when the upload path is dynamic.

Example fix

# before
ref = FileReference(file_id="file-abc123", content_type="image/png")  # file_uri empty
block = gemini_formatter.format_block(ref)  # raises

# after
ref = FileReference(file_uri="https://generativelanguage.googleapis.com/v1beta/files/xyz", content_type="image/png")
block = gemini_formatter.format_block(ref)

if isinstance(resolved, FileReference) and not resolved.file_uri:
    raise ValueError(f"'{file.filename}' was not uploaded via the Gemini Files API; missing file_uri")

def is_gemini_ready(ref: FileReference) -> TypeGuard[FileReference]:
    return bool(ref.file_uri)

try:
    block = gemini_formatter.format_block(resolved)
except ValueError as e:
    if "file_uri" in str(e):
        resolved = upload_to_gemini_files(resolved)  # sets file_uri, then retry
    else:
        raise

When it happens

Trigger: Passing a FileReference whose file_uri is None/empty to GeminiFormatter.format_block(). Common when the FileReference was produced by uploading to a non-Gemini backend (only file_id set) or hand-constructed without file_uri.

Common situations: Using the OpenAI files API upload then routing to a Gemini model; reusing a cached/stale FileReference after its upload metadata was lost; constructing FileReference(file_id=...) by copy-paste from OpenAI examples.

Related errors

• Bedrock requires file_uri for FileReference (S3 URI)
• Bedrock does not support URL references - resolve to bytes f
• Unsupported content type for Responses API: {content_type}
• google-genai is required for Gemini file uploads. Install wi
• Video processing failed for {file.filename}

AI-assisted analysis of crewAIInc/crewAI@754d7323be (2026-08-15). Data as JSON: /api/errors/3c9e002cee0c63b0. Report an issue: GitHub.