fix(backend): return 400 for chat attachments the file pipeline cannot process (#11853)

POST /v1|/v2/files answered HTTP 500 for two kinds of ordinary user input,
observed live on prod image c5b0b5d (api.omi.me):

  PIL.UnidentifiedImageError: cannot identify image file '/tmp/<uuid>_<name>.heic'
    routers/chat.py -> chat_file.FileChatTool.upload -> File.generate_thumbnail
  openai.BadRequestError: Error code: 400 - Invalid extension ogg
    routers/chat.py -> chat_file.FileChatTool.upload -> openai.files.create

mimetypes maps .heic to image/heic, so File.is_image() is true and the thumbnail
step runs even though Pillow ships no HEIF decoder -- an iPhone camera-roll photo
crashed the route. An .ogg voice note reached OpenAI Files, whose accepted-extension
list has no audio formats, and the provider's 400 propagated unhandled.

Both are request input arriving over a public route, so both belong on the 4xx side
of the request boundary. chat_file now raises a typed UnsupportedChatFileError at the
two points where an unprocessable file is identified, and both upload endpoints map it
to HTTPException(400) with the extension in the detail. Nothing else changes: the
provider is not called for an undecodable image, and supported files upload as before.

Verification
  - New tests/unit/test_chat_file_upload_unsupported.py drives POST /v2/files and
    POST /v1/files over HTTP against the real routers.chat and the real
    utils.other.chat_file (only the provider client, auth and Firestore stubbed):
    heic -> 400, provider-rejected extension -> 400, text/plain -> 200 and persisted.
  - Control against pre-fix source: 4 of the 5 fail with the verbatim prod exceptions
    (UnidentifiedImageError, openai.BadRequestError); the happy-path test passes both
    before and after, confirming no behavior change there.
  - Real file, not a synthetic blob: a HEIC produced by macOS `sips -s format heic`
    raises the same UnidentifiedImageError in Pillow 12.2, and driving that file
    through POST /v2/files returns 500 on pre-fix source and
    400 {"detail":"Unsupported attachment: 'heic' files are not supported in chat."}
    with the fix.
  - _chat_router_test_harness stubs utils.other.chat_file with the exact leaves
    routers.chat imports, so the new name was added to that stub inventory; without it
    test_chat_stream_error_fallback (11) and test_chat_quota_counting_router (9) fail
    to import. Both green again.
  - backend/test.sh over the 17 chat/file/upload suites: 64 passed, 5 deselected.

Failure-Class: new

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: kodjima33

.github/failure-classes/FC-request-input-rejection-escapes-as-server-fault.json

@@ -0,0 +1,18 @@
+{
+  "schema_version": 1,
+  "id": "FC-request-input-rejection-escapes-as-server-fault",
+  "violated_contract": "A route owns the classification of its own request input. When a library or an upstream provider rejects something the caller supplied -- a media type with no decoder, an extension outside a vendor's accepted set -- that rejection is a bad request, and the route must answer 4xx. Letting the library's or provider's exception propagate turns ordinary user input into a 5xx: the client can say nothing useful to the user, the failure is indistinguishable from a real outage in serving metrics, and every retry re-pages.",
+  "canonical_prevention": "Catch the narrow, input-caused exception types at the point where the unprocessable input is identified, convert them to one typed domain error, and map that error to an explicit 4xx at the route boundary with a detail the client can show. Catch only the input-caused types -- transport, disk and quota failures must still surface as 5xx, because those are server faults. A regression test drives the real route over HTTP with the offending input and asserts the status code the client receives.",
+  "canonical_prevention_artifact": [
+    "backend/utils/other/chat_file.py",
+    "backend/routers/chat.py",
+    "backend/tests/unit/test_chat_file_upload_unsupported.py"
+  ],
+  "evidence_prs": [
+    11853
+  ],
+  "scope_hints": [
+    "backend/routers/**"
+  ],
+  "status": "open"
+}

backend/routers/chat.py

@@ -67,7 +67,7 @@
 from utils.subscription import enforce_chat_quota, is_trial_paywalled
 from utils import share_links
 from utils.other import endpoints as auth, storage
-from utils.other.chat_file import FileChatTool
+from utils.other.chat_file import FileChatTool, UnsupportedChatFileError
 from utils.multipart import (
     CHAT_FILE_MAX_PART_SIZE,
     MultipartMaxPartSizeRoute,
@@ -1515,7 +1515,10 @@ def upload_file_chat(
             with temp_file.open("wb") as buffer:
                 shutil.copyfileobj(file.file, buffer)
 
-            result = FileChatTool.upload(temp_file)
+            try:
+                result = FileChatTool.upload(temp_file)
+            except UnsupportedChatFileError as error:
+                raise HTTPException(status_code=400, detail=str(error))
 
             thumb_name = result.get("thumbnail_name", "")
             if thumb_name != "":
@@ -1580,7 +1583,10 @@ def upload_file_chat_v1(
             with temp_file.open("wb") as buffer:
                 shutil.copyfileobj(file.file, buffer)
 
-            result = FileChatTool.upload(temp_file)
+            try:
+                result = FileChatTool.upload(temp_file)
+            except UnsupportedChatFileError as error:
+                raise HTTPException(status_code=400, detail=str(error))
 
             thumb_name = result.get("thumbnail_name", "")
             if thumb_name != "":

backend/tests/unit/_chat_router_test_harness.py

@@ -177,6 +177,9 @@ def with_rate_limit(func, _policy):
     storage.schedule_syncing_temporal_file_deletion = MagicMock()
     chat_file = install('utils.other.chat_file', ModuleType('utils.other.chat_file'))
     chat_file.FileChatTool = MagicMock()
+    # routers.chat imports this name; the stub must carry it or the module fails to load. A local
+    # subclass keeps the real module (PIL, openai, database) out of these suites' import graph.
+    chat_file.UnsupportedChatFileError = type('UnsupportedChatFileError', (Exception,), {})
 
     sync_files = install('utils.sync.files', ModuleType('utils.sync.files'))
     sync_files.retrieve_file_paths = MagicMock(return_value=[])

backend/tests/unit/test_chat_file_upload_unsupported.py

@@ -0,0 +1,148 @@
+"""POST /v1|/v2/files answers 400 for a file type the pipeline cannot process, never 500.
+
+Live prod signature (backend image c5b0b5d, api.omi.me):
+  * ``PIL.UnidentifiedImageError: cannot identify image file '/tmp/<uuid>_<name>.heic'``
+    - mimetypes maps .heic to image/heic, so File.is_image() is true and generate_thumbnail()
+      runs, but Pillow ships no HEIF decoder. An iPhone camera-roll photo 500'd.
+  * ``openai.BadRequestError: Invalid extension ogg`` from openai.files.create - the provider's
+    accepted-extension list has no audio formats. An .ogg voice note 500'd.
+
+Both are ordinary user input arriving over a public route, so both belong on the 4xx side of the
+request boundary. The route is driven over HTTP here (real routers.chat, real utils.other.chat_file)
+so the assertion is the status code the client actually receives.
+"""
+
+import sys
+from types import ModuleType, SimpleNamespace
+from unittest.mock import MagicMock
+
+import openai
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from tests.unit import _chat_router_test_harness as harness
+from tests.unit._chat_router_test_harness import BACKEND_DIR
+
+# A one-byte payload with a .heic name: mimetypes keys off the extension, and Pillow fails to
+# identify the bytes exactly as it does for real HEIC input.
+HEIC_BYTES = b'\x00\x00\x00\x18ftypheic\x00\x00\x00\x00heicmif1'
+OGG_BYTES = b'OggS\x00\x02' + b'\x00' * 20
+
+
+def _make_chat_client():
+    saved = {k: v for k, v in sys.modules.items()}
+
+    harness.install_package('models', BACKEND_DIR / 'models')
+    harness.install_package('database', BACKEND_DIR / 'database')
+    harness.install_package('utils', BACKEND_DIR / 'utils')
+    harness.install_package('utils.other', BACKEND_DIR / 'utils' / 'other')
+    harness.install_package('utils.sync', BACKEND_DIR / 'utils' / 'sync')
+    harness.install_package('utils.stt', BACKEND_DIR / 'utils' / 'stt')
+    harness.install_package('utils.llm', BACKEND_DIR / 'utils' / 'llm')
+    harness.install_package('utils.retrieval', BACKEND_DIR / 'utils' / 'retrieval')
+
+    harness.wire_common_stubs(harness.install_module)
+    harness.install_module('models.app')
+
+    # The gateway telemetry chat_file imports is out of scope here (and pulls the real gateway
+    # client stack in); keep it inert so the upload path itself is what runs.
+    gateway_client = harness.install_module('utils.llm.gateway_client', ModuleType('utils.llm.gateway_client'))
+    gateway_client.should_route_features_through_gateway = MagicMock(return_value=False)
+    gateway_obs = harness.install_module(
+        'utils.llm.gateway_observability', ModuleType('utils.llm.gateway_observability')
+    )
+    gateway_obs.record_direct_exception_surface = MagicMock()
+
+    # wire_common_stubs replaces chat_file with a MagicMock; this suite needs the real module,
+    # because the defect lives in its PIL and provider error handling.
+    harness.load_real_module('utils.other.chat_file', BACKEND_DIR / 'utils' / 'other' / 'chat_file.py')
+
+    chat_utils = harness.install_module('utils.chat', ModuleType('utils.chat'))
+    for name in (
+        'acquire_chat_session',
+        'emit_stream_error_fallback',
+        'initial_message_util',
+        'process_voice_message_segment_stream',
+        'resolve_voice_message_language',
+        'transcribe_voice_message_segment',
+        'transcribe_pcm_bytes',
+    ):
+        setattr(chat_utils, name, MagicMock())
+
+    graph = harness.install_module('utils.retrieval.graph', ModuleType('utils.retrieval.graph'))
+    graph.execute_chat_stream = MagicMock()
+    graph.execute_graph_chat = MagicMock()
+    graph.execute_persona_chat_stream = MagicMock()
+
+    sys.modules.pop('routers.chat', None)
+    module = harness.load_real_module('routers.chat', BACKEND_DIR / 'routers' / 'chat.py')
+
+    app = FastAPI()
+    app.include_router(module.router)
+    return TestClient(app), module, saved
+
+
+@pytest.fixture
+def chat_client():
+    client, module, saved = _make_chat_client()
+    try:
+        yield client, module
+    finally:
+        harness.cleanup(saved)
+
+
+def _bad_request(**_kwargs):
+    raise openai.BadRequestError(
+        message="Error code: 400 - Invalid extension ogg.",
+        response=SimpleNamespace(request=None, status_code=400, headers={}),
+        body=None,
+    )
+
+
+@pytest.mark.parametrize('route', ['/v2/files', '/v1/files'])
+def test_heic_photo_is_rejected_as_bad_request(chat_client, route, monkeypatch):
+    client, module = chat_client
+    chat_file = sys.modules['utils.other.chat_file']
+    # Nothing should reach the provider: the failure is local, in thumbnail generation.
+    monkeypatch.setattr(chat_file.openai, 'files', SimpleNamespace(create=_unreachable))
+
+    response = client.post(route, files={'files': ('photo.heic', HEIC_BYTES, 'image/heic')})
+
+    assert response.status_code == 400
+    assert 'heic' in response.json()['detail']
+    module.chat_db.add_multi_files.assert_not_called()
+
+
+@pytest.mark.parametrize('route', ['/v2/files', '/v1/files'])
+def test_provider_rejected_extension_is_bad_request(chat_client, route, monkeypatch):
+    client, module = chat_client
+    chat_file = sys.modules['utils.other.chat_file']
+    monkeypatch.setattr(chat_file.openai, 'files', SimpleNamespace(create=_bad_request))
+
+    response = client.post(route, files={'files': ('note.ogg', OGG_BYTES, 'audio/ogg')})
+
+    assert response.status_code == 400
+    assert 'ogg' in response.json()['detail']
+    module.chat_db.add_multi_files.assert_not_called()
+
+
+def test_supported_file_still_uploads(chat_client, monkeypatch):
+    """The guard must not swallow the happy path."""
+    client, module = chat_client
+    chat_file = sys.modules['utils.other.chat_file']
+    monkeypatch.setattr(
+        chat_file.openai,
+        'files',
+        SimpleNamespace(create=lambda **_kwargs: SimpleNamespace(id='file-1', filename='note.txt')),
+    )
+
+    response = client.post('/v2/files', files={'files': ('note.txt', b'hello', 'text/plain')})
+
+    assert response.status_code == 200
+    assert response.json()[0]['openai_file_id'] == 'file-1'
+    module.chat_db.add_multi_files.assert_called_once()
+
+
+def _unreachable(**_kwargs):
+    raise AssertionError('provider upload must not be attempted for an undecodable image')

backend/utils/other/chat_file.py

@@ -11,7 +11,7 @@
     ChatCompletionContentPartParam,
     ChatCompletionMessageParam,
 )
-from PIL import Image
+from PIL import Image, UnidentifiedImageError
 from pydantic import ValidationError
 
 import database.chat as chat_db
@@ -26,6 +26,21 @@
 _FILE_SEARCH_ASSISTANT_MODEL = "gpt-4.1"
 
 
+class UnsupportedChatFileError(Exception):
+    """A chat attachment this pipeline cannot process.
+
+    The upload routes own the client contract: a file type we cannot handle is bad request
+    input, not a server fault. Without this, PIL (an iPhone .heic photo has no decoder) and
+    OpenAI Files (an .ogg voice note is not an accepted extension) escape as 500s.
+    """
+
+
+def _unsupported_chat_file_error(file_path: Union[str, Path]) -> UnsupportedChatFileError:
+    suffix = Path(file_path).suffix.lstrip('.').lower()
+    label = f"'{suffix}' files are" if suffix else "this file type is"
+    return UnsupportedChatFileError(f"Unsupported attachment: {label} not supported in chat.")
+
+
 def _safe_file_chats(files_data: List[Dict[str, Any]]) -> List[FileChat]:
     """Build FileChat objects from raw file docs, skipping (not raising on) a malformed one.
 
@@ -158,12 +173,20 @@ def upload(file_path: Union[str, Path]) -> Dict[str, Any]:
         file.get_mime_type()
 
         if file.is_image():
-            file.generate_thumbnail()
+            try:
+                file.generate_thumbnail()
+            except UnidentifiedImageError as error:
+                # An image mime type Pillow has no decoder for (.heic from an iPhone camera roll).
+                raise _unsupported_chat_file_error(file_path) from error
             file.purpose = "vision"
 
         with open(file_path, 'rb') as f:
             # upload file to OpenAI
-            response = openai.files.create(file=f, purpose=cast(Any, file.purpose))
+            try:
+                response = openai.files.create(file=f, purpose=cast(Any, file.purpose))
+            except openai.BadRequestError as error:
+                # The provider rejects the extension (audio/video, archives it does not index).
+                raise _unsupported_chat_file_error(file_path) from error
             if response:
                 file.file_id = response.id
                 file.file_name = response.filename