{"record":{"id":"3c9e002cee0c63b0","repo":"crewAIInc/crewAI","slug":"gemini-requires-file-uri-for-filereference","errorCode":null,"errorMessage":"Gemini requires file_uri for FileReference","messagePattern":"Gemini requires file_uri for FileReference","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"lib/crewai-files/src/crewai_files/formatting/gemini.py","lineNumber":35,"sourceCode":"class GeminiFormatter:\n    \"\"\"Formats resolved files into Gemini content blocks.\"\"\"\n\n    @staticmethod\n    def format_block(resolved: ResolvedFileType) -> dict[str, Any]:\n        \"\"\"Format a resolved file into a Gemini content block.\n\n        Args:\n            resolved: Resolved file.\n\n        Returns:\n            Content block dict.\n\n        Raises:\n            TypeError: If resolved type is not supported.\n        \"\"\"\n        if isinstance(resolved, FileReference):\n            if not resolved.file_uri:\n                raise ValueError(\"Gemini requires file_uri for FileReference\")\n            return {\n                \"fileData\": {\n                    \"mimeType\": resolved.content_type,\n                    \"fileUri\": resolved.file_uri,\n                }\n            }\n\n        if isinstance(resolved, UrlReference):\n            return {\n                \"fileData\": {\n                    \"mimeType\": resolved.content_type,\n                    \"fileUri\": resolved.url,\n                }\n            }\n\n        if isinstance(resolved, InlineBase64):\n            return {\n                \"inlineData\": {","sourceCodeStart":17,"sourceCodeEnd":53,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/crewai-files/src/crewai_files/formatting/gemini.py#L17-L53","documentation":"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').","triggerScenarios":"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.","commonSituations":"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.","solutions":["Upload the file through the Gemini Files API and pass the returned uri in FileReference(file_uri=..., content_type=...).","Or skip the reference entirely and pass inline bytes/base64, which the Gemini formatter also supports.","Check resolved.file_uri is truthy before calling format_block when the upload path is dynamic."],"exampleFix":"# before\nref = FileReference(file_id=\"file-abc123\", content_type=\"image/png\")  # file_uri empty\nblock = gemini_formatter.format_block(ref)  # raises\n\n# after\nref = FileReference(file_uri=\"https://generativelanguage.googleapis.com/v1beta/files/xyz\", content_type=\"image/png\")\nblock = gemini_formatter.format_block(ref)","handlingStrategy":"type-guard","validationCode":"if isinstance(resolved, FileReference) and not resolved.file_uri:\n    raise ValueError(f\"'{file.filename}' was not uploaded via the Gemini Files API; missing file_uri\")","typeGuard":"def is_gemini_ready(ref: FileReference) -> TypeGuard[FileReference]:\n    return bool(ref.file_uri)","tryCatchPattern":"try:\n    block = gemini_formatter.format_block(resolved)\nexcept ValueError as e:\n    if \"file_uri\" in str(e):\n        resolved = upload_to_gemini_files(resolved)  # sets file_uri, then retry\n    else:\n        raise","preventionTips":["Upload through the Gemini Files API and store the returned uri on the FileReference.","Use inline base64 for small files to skip the reference path entirely.","Assert file_uri is set after any upload/resolution step."],"tags":["gemini","filereference","files-api","formatter"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}