fix: raise ValueError for unsupported MIME types in file_data URI path

Merge #5023

Fixes #5022

## Problem

When a `Part` with `file_data.file_uri` has no determinable MIME type, the library fell back to `application/octet-stream` via `_DEFAULT_MIME_TYPE`. This value then propagated to LiteLLM which raised a cryptic internal `ValueError` with no guidance for the user.

The same failure occurred when the caller explicitly set `mime_type = "application/octet-stream"` on the Part. Both cases reach the same failure point.

There was also an inconsistency between the two content paths:

- The `inline_data` path raises `ValueError` immediately for unsupported MIME types
- The `file_data` path silently used a fallback and failed later with a cryptic message

`GcsArtifactService` generates URIs like `gs://bucket/artifact/0` with no extension and no MIME type, making ADK's own artifact system the primary trigger for this fallback.

## Fix

Removes `_DEFAULT_MIME_TYPE` and raises `ValueError` early with an actionable message when the resolved MIME type is either unknown or `application/octet-stream`. This aligns the `file_data` path with the existing fail-fast behavior of the `inline_data` path.

The logic order is also corrected so providers that always produce a text fallback (anthropic, non-Gemini Vertex AI) and OpenAI/Azure HTTP media URLs are handled before the MIME type guard, keeping those paths unaffected.

## Changes

- `src/google/adk/models/lite_llm.py`: remove `_DEFAULT_MIME_TYPE`, restructure file_uri handling block, raise `ValueError` for missing or generic MIME types
- `tests/unittests/models/test_litellm.py`: update two existing tests to assert the new `ValueError`, add one new test covering explicit `application/octet-stream`

## Testing

```
pytest tests/unittests/models/test_litellm.py
241 passed, 5 errors (pre-existing, missing pytest-mock fixture)
```

Format verified with `pyink`. mypy error count unchanged from main (26).

Co-authored-by: George Weale <gweale@google.com>
COPYBARA_INTEGRATE_REVIEW=#5023 from Raman369AI:fix/file-uri-unknown-mime-type-error c7eb917
PiperOrigin-RevId: 938679610

Author: 2 people

src/google/adk/models/lite_llm.py

@@ -330,10 +330,6 @@ def _get_provider_from_model(model: str) -> str:
   return ""
 
 
-# Default MIME type when none can be inferred
-_DEFAULT_MIME_TYPE = "application/octet-stream"
-
-
 def _infer_mime_type_from_uri(uri: str) -> Optional[str]:
   """Attempts to infer MIME type from a URI's path extension.
 
@@ -1217,33 +1213,33 @@ async def _get_content(
         })
         continue
 
-      # Determine MIME type: use explicit value, infer from URI, or use default.
+      # Resolve MIME type early: needed before the media-URL shortcut below,
+      # which must run before the generic text-fallback check. The raise is
+      # deferred until after all early-continue paths so that providers which
+      # always fall back to text (anthropic, non-Gemini Vertex AI) are never
+      # asked for a MIME type they cannot supply.
       mime_type = part.file_data.mime_type
       if not mime_type:
         mime_type = _infer_mime_type_from_uri(part.file_data.file_uri)
       if not mime_type and part.file_data.display_name:
         guessed_mime_type, _ = mimetypes.guess_type(part.file_data.display_name)
         mime_type = guessed_mime_type
-      if not mime_type:
-        # LiteLLM's Vertex AI backend requires format for GCS URIs.
-        mime_type = _DEFAULT_MIME_TYPE
-        logger.debug(
-            "Could not determine MIME type for file_uri %s, using default: %s",
-            part.file_data.file_uri,
-            mime_type,
-        )
-      mime_type = _normalize_mime_type(mime_type)
+      if mime_type:
+        mime_type = _normalize_mime_type(mime_type)
 
+      # For OpenAI/Azure: HTTP media URLs (image, video, audio) are sent as
+      # typed URL blocks and must be handled before the generic text fallback.
       if provider in _FILE_ID_REQUIRED_PROVIDERS and _is_http_url(
           part.file_data.file_uri
       ):
-        url_content_type = _media_url_content_type(mime_type)
-        if url_content_type:
-          content_objects.append({
-              "type": url_content_type,
-              url_content_type: {"url": part.file_data.file_uri},
-          })
-          continue
+        if mime_type:
+          url_content_type = _media_url_content_type(mime_type)
+          if url_content_type:
+            content_objects.append({
+                "type": url_content_type,
+                url_content_type: {"url": part.file_data.file_uri},
+            })
+            continue
 
       if not _is_file_uri_supported(provider, model, part.file_data.file_uri):
         redacted_file_uri = _redact_file_uri_for_log(
@@ -1255,6 +1251,19 @@ async def _get_content(
             f" {provider}."
         )
 
+      # All remaining providers (e.g. Vertex AI + Gemini) require a specific
+      # MIME type in the file object. Both a missing type and
+      # 'application/octet-stream' cause a downstream ValueError from LiteLLM
+      # regardless of whether the value was set explicitly by the caller or
+      # arrived via a default fallback; raise early with an actionable message.
+      if not mime_type or mime_type == "application/octet-stream":
+        type_label = mime_type or "(unknown)"
+        raise ValueError(
+            f"Cannot process file_uri {part.file_data.file_uri!r}: MIME type"
+            f" {type_label!r} is not supported. Please set a specific MIME"
+            " type on `file_data.mime_type`."
+        )
+
       file_object: ChatCompletionFileUrlObject = {
           "file_id": part.file_data.file_uri,
       }

tests/unittests/models/test_litellm.py

@@ -1972,14 +1972,12 @@ async def test_content_to_message_param_user_message_file_uri_only(
 
 @pytest.mark.asyncio
 async def test_content_to_message_param_user_message_file_uri_without_mime_type():
-  """Test handling of file_data without mime_type (GcsArtifactService scenario).
+  """Test that file_data without an inferable mime_type raises ValueError.
 
   When using GcsArtifactService, artifacts may have file_uri (gs://...) but
-  without mime_type set. LiteLLM's Vertex AI backend requires the format
-  field to be present, so we infer MIME type from the URI extension or use
-  a default fallback to ensure compatibility.
-
-  See: https://github.com/google/adk-python/issues/3787
+  without mime_type set. When the MIME type cannot be determined from the URI
+  extension or display_name, ADK raises a clear ValueError rather than
+  forwarding an unsupported 'application/octet-stream' to LiteLLM.
   """
   file_part = types.Part(
       file_data=types.FileData(
@@ -1994,22 +1992,34 @@ async def test_content_to_message_param_user_message_file_uri_without_mime_type(
       ],
   )
 
-  message = await _content_to_message_param(content)
-  assert message == {
-      "role": "user",
-      "content": [
-          {"type": "text", "text": "Analyze this file."},
-          {
-              "type": "file",
-              "file": {
-                  "file_id": (
-                      "gs://agent-artifact-bucket/app/user/session/artifact/0"
-                  ),
-                  "format": "application/octet-stream",
-              },
-          },
+  with pytest.raises(ValueError, match="Cannot process file_uri"):
+    await _content_to_message_param(content)
+
+
+@pytest.mark.asyncio
+async def test_content_to_message_param_user_message_file_uri_explicit_octet_stream():
+  """Test that an explicit application/octet-stream MIME type raises ValueError.
+
+  Upstream callers may explicitly set mime_type to 'application/octet-stream'
+  when the true type is unknown. ADK treats this identically to a missing MIME
+  type and raises early rather than forwarding the unsupported type to LiteLLM.
+  """
+  file_part = types.Part(
+      file_data=types.FileData(
+          file_uri="gs://agent-artifact-bucket/app/user/session/artifact/0",
+          mime_type="application/octet-stream",
+      )
+  )
+  content = types.Content(
+      role="user",
+      parts=[
+          types.Part.from_text(text="Analyze this file."),
+          file_part,
       ],
-  }
+  )
+
+  with pytest.raises(ValueError, match="application/octet-stream"):
+    await _content_to_message_param(content)
 
 
 @pytest.mark.asyncio
@@ -2018,8 +2028,6 @@ async def test_content_to_message_param_user_message_file_uri_infer_mime_type():
 
   When file_data has a file_uri with a recognizable extension but no explicit
   mime_type, the MIME type should be inferred from the extension.
-
-  See: https://github.com/google/adk-python/issues/3787
   """
   file_part = types.Part(
       file_data=types.FileData(
@@ -3293,8 +3301,6 @@ async def test_get_content_file_uri_infer_mime_type():
 
   When file_data has a file_uri with a recognizable extension but no explicit
   mime_type, the MIME type should be inferred from the extension.
-
-  See: https://github.com/google/adk-python/issues/3787
   """
   # Use Part constructor directly to test MIME type inference in _get_content
   # (types.Part.from_uri does its own inference, so we bypass it)
@@ -3344,27 +3350,38 @@ async def test_get_content_file_uri_infers_from_display_name():
 
 @pytest.mark.asyncio
 async def test_get_content_file_uri_default_mime_type():
-  """Test that file_uri without extension uses default MIME type.
+  """Test that file_uri without an inferable extension raises ValueError.
 
   When file_data has a file_uri without a recognizable extension and no explicit
-  mime_type, a default MIME type should be used to ensure compatibility with
-  LiteLLM backends.
-
-  See: https://github.com/google/adk-python/issues/3787
+  mime_type, ADK raises a clear ValueError instead of forwarding the unsupported
+  'application/octet-stream' MIME type to LiteLLM.
   """
-  # Use Part constructor directly to create file_data without mime_type
-  # (types.Part.from_uri requires a valid mime_type when it can't infer)
   parts = [
       types.Part(file_data=types.FileData(file_uri="gs://bucket/artifact/0"))
   ]
-  content = await _get_content(parts)
-  assert content[0] == {
-      "type": "file",
-      "file": {
-          "file_id": "gs://bucket/artifact/0",
-          "format": "application/octet-stream",
-      },
-  }
+  with pytest.raises(ValueError, match="Cannot process file_uri"):
+    await _get_content(parts)
+
+
+@pytest.mark.asyncio
+async def test_get_content_file_uri_explicit_octet_stream_raises():
+  """Test that an explicit application/octet-stream MIME type raises ValueError.
+
+  'application/octet-stream' is semantically equivalent to an unknown type and
+  causes the same downstream ValueError from LiteLLM whether it arrives as a
+  default fallback or is set explicitly by the caller. ADK raises early with
+  an actionable message in both cases.
+  """
+  parts = [
+      types.Part(
+          file_data=types.FileData(
+              file_uri="gs://bucket/artifact/0",
+              mime_type="application/octet-stream",
+          )
+      )
+  ]
+  with pytest.raises(ValueError, match="application/octet-stream"):
+    await _get_content(parts)
 
 
 @pytest.mark.asyncio