{"record":{"id":"ff90c74a6f86d8cf","repo":"huggingface/transformers","slug":"unexpected-fields-in-the-request-unexpected","errorCode":null,"errorMessage":"Unexpected fields in the request: {unexpected}","messagePattern":"Unexpected fields in the request: (.+?)","errorType":"http","errorClass":"HTTPException","httpStatus":422,"severity":"error","filePath":"src/transformers/cli/serving/transcription.py","lineNumber":80,"sourceCode":"    Standalone (does not extend :class:`BaseHandler`) because audio requests use\n    multipart form data, not JSON bodies, and don't need generation config or\n    validation. Shares the :class:`GenerationState` for thread safety.\n    \"\"\"\n\n    def __init__(self, model_manager: ModelManager, generation_state: GenerationState):\n        \"\"\"\n        Args:\n            model_manager (`ModelManager`): Handles model loading, caching, and lifecycle.\n            generation_state (`GenerationState`): Shared generation state for thread safety.\n        \"\"\"\n        self.model_manager = model_manager\n        self.generation_state = generation_state\n\n    def _validate_request(self, form_keys: set[str]) -> None:\n        \"\"\"Validate transcription request fields.\"\"\"\n        unexpected = form_keys - getattr(TransformersTranscriptionCreateParams, \"__mutable_keys__\", set())\n        if unexpected:\n            raise HTTPException(status_code=422, detail=f\"Unexpected fields in the request: {unexpected}\")\n        unused = form_keys & UNUSED_TRANSCRIPTION_FIELDS\n        if unused:\n            logger.warning_once(f\"Ignoring unsupported fields in the request: {unused}\")\n\n    async def handle_request(self, request: Request) -> JSONResponse | StreamingResponse:\n        \"\"\"Parse multipart form, run transcription, return result.\n\n        Args:\n            request (`Request`): FastAPI request containing multipart form data with\n                ``file`` (audio bytes), ``model`` (model ID), and optional ``stream`` flag.\n\n        Returns:\n            `JSONResponse | StreamingResponse`: Transcription result or SSE stream.\n        \"\"\"\n        from transformers.utils.import_utils import is_librosa_available, is_multipart_available\n\n        if not is_librosa_available():\n            raise ImportError(\"Missing librosa dependency for audio transcription. Install with `pip install librosa`\")","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/cli/serving/transcription.py#L62-L98","documentation":"Raised as HTTP 422 by the transcription request validator in the serving CLI. It compares the multipart form keys against the mutable keys of TransformersTranscriptionCreateParams and rejects any field the API does not know about. Unknown-but-recognized fields (UNUSED_TRANSCRIPTION_FIELDS) are only warned about, but truly unexpected fields hard-fail.","triggerScenarios":"POST /v1/audio/transcriptions with a multipart form containing fields not in TransformersTranscriptionCreateParams, e.g. 'temperature', 'language_hints', or misspellings like 'modell'.","commonSituations":"Porting a client from the OpenAI Whisper API which sends extra parameters this server does not accept; copy-pasted curl commands with legacy field names; SDKs that inject extra metadata form fields.","solutions":["Remove the listed unexpected fields from the multipart form (the error message names them explicitly)","Check TransformersTranscriptionCreateParams.__mutable_keys__ for the exact accepted field set","Fields you intended as no-ops may belong to UNUSED_TRANSCRIPTION_FIELDS (warning only) — but fields outside both sets must be dropped"],"exampleFix":"# before\nfiles = {'file': fh, 'model': 'whisper', 'temperature': '0.5'}\n# after\nfiles = {'file': fh, 'model': 'whisper'}","handlingStrategy":"validation","validationCode":"from transformers.cli.serving.transcription import TransformersTranscriptionCreateParams, UNUSED_TRANSCRIPTION_FIELDS\nallowed = set(TransformersTranscriptionCreateParams.__mutable_keys__)\nsent = {'file', 'model', 'stream'}\nassert not (sent - allowed), f'unexpected fields: {sent - allowed}'","typeGuard":null,"tryCatchPattern":"if resp.status_code == 422 and 'Unexpected fields' in resp.text:\n    detail = resp.json()['detail']\n    drop = set(re.findall(r\"'([^']+)'\", detail))\n    form = {k: v for k, v in form.items() if k not in drop}\n    resp = requests.post(url, files=form)","preventionTips":["Derive the form schema from __mutable_keys__ instead of hardcoding field lists","Keep a single constants module naming the accepted transcription fields in client code"],"tags":["api","serving","audio","validation","http-422"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}