huggingface/transformers · error · HTTPException

Unexpected fields in the request: {unexpected}

Error message

Unexpected fields in the request: {unexpected}

What it means

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.

Source

Thrown at src/transformers/cli/serving/transcription.py:80

    Standalone (does not extend :class:`BaseHandler`) because audio requests use
    multipart form data, not JSON bodies, and don't need generation config or
    validation. Shares the :class:`GenerationState` for thread safety.
    """

    def __init__(self, model_manager: ModelManager, generation_state: GenerationState):
        """
        Args:
            model_manager (`ModelManager`): Handles model loading, caching, and lifecycle.
            generation_state (`GenerationState`): Shared generation state for thread safety.
        """
        self.model_manager = model_manager
        self.generation_state = generation_state

    def _validate_request(self, form_keys: set[str]) -> None:
        """Validate transcription request fields."""
        unexpected = form_keys - getattr(TransformersTranscriptionCreateParams, "__mutable_keys__", set())
        if unexpected:
            raise HTTPException(status_code=422, detail=f"Unexpected fields in the request: {unexpected}")
        unused = form_keys & UNUSED_TRANSCRIPTION_FIELDS
        if unused:
            logger.warning_once(f"Ignoring unsupported fields in the request: {unused}")

    async def handle_request(self, request: Request) -> JSONResponse | StreamingResponse:
        """Parse multipart form, run transcription, return result.

        Args:
            request (`Request`): FastAPI request containing multipart form data with
                ``file`` (audio bytes), ``model`` (model ID), and optional ``stream`` flag.

        Returns:
            `JSONResponse | StreamingResponse`: Transcription result or SSE stream.
        """
        from transformers.utils.import_utils import is_librosa_available, is_multipart_available

        if not is_librosa_available():
            raise ImportError("Missing librosa dependency for audio transcription. Install with `pip install librosa`")

View on GitHub (pinned to a597f97485)

Solutions

1. Remove the listed unexpected fields from the multipart form (the error message names them explicitly)
2. Check TransformersTranscriptionCreateParams.__mutable_keys__ for the exact accepted field set
3. Fields you intended as no-ops may belong to UNUSED_TRANSCRIPTION_FIELDS (warning only) — but fields outside both sets must be dropped

Example fix

# before
files = {'file': fh, 'model': 'whisper', 'temperature': '0.5'}
# after
files = {'file': fh, 'model': 'whisper'}

from transformers.cli.serving.transcription import TransformersTranscriptionCreateParams, UNUSED_TRANSCRIPTION_FIELDS
allowed = set(TransformersTranscriptionCreateParams.__mutable_keys__)
sent = {'file', 'model', 'stream'}
assert not (sent - allowed), f'unexpected fields: {sent - allowed}'

if resp.status_code == 422 and 'Unexpected fields' in resp.text:
    detail = resp.json()['detail']
    drop = set(re.findall(r"'([^']+)'", detail))
    form = {k: v for k, v in form.items() if k not in drop}
    resp = requests.post(url, files=form)

When it happens

Trigger: POST /v1/audio/transcriptions with a multipart form containing fields not in TransformersTranscriptionCreateParams, e.g. 'temperature', 'language_hints', or misspellings like 'modell'.

Common situations: 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.

Related errors

• 'input' must be a string or list
• Unsupported input item type: {item_type!r}
• Missing `model` field in the request body.
• Expected file upload, got string
• Expected model name as string

AI-assisted analysis of huggingface/transformers@a597f97485 (2026-08-14). Data as JSON: /api/errors/ff90c74a6f86d8cf. Report an issue: GitHub.