huggingface/transformers · error · HTTPException

Expected model name as string

Error message

Expected model name as string

What it means

HTTP 422 from the transcription handler when the multipart 'model' field is not a string. Multipart values are strings or UploadFile objects; this check rejects requests that upload a file under the 'model' key or otherwise send a non-text part, before process_model_name would fail confusingly.

Source

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

        """
        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`")
        if not is_multipart_available():
            raise ImportError(
                "Missing python-multipart dependency for file uploads. Install with `pip install python-multipart`"
            )

        async with request.form() as form:
            self._validate_request(set(form.keys()))
            file_field = form["file"]
            if isinstance(file_field, str):
                raise HTTPException(status_code=422, detail="Expected file upload, got string")
            file_bytes = await file_field.read()
            model = form["model"]
            if not isinstance(model, str):
                raise HTTPException(status_code=422, detail="Expected model name as string")
            stream = str(form.get("stream", "false")).lower() == "true"

        model_id_and_revision = self.model_manager.process_model_name(model)
        audio_model, audio_processor = self.model_manager.load_model_and_processor(model_id_and_revision)
        base_manager = self.generation_state.get_manager(model_id_and_revision)
        if not isinstance(base_manager, GenerateManager):
            raise HTTPException(status_code=400, detail="Audio transcription requires sequential generation (not CB)")
        gen_manager = base_manager
        audio_inputs = self._prepare_audio_inputs(file_bytes, audio_processor, audio_model)

        if stream:
            return self._streaming(gen_manager, audio_model, audio_processor, audio_inputs)
        return await self._non_streaming(gen_manager, audio_model, audio_processor, audio_inputs)

    @staticmethod
    def _prepare_audio_inputs(
        file_bytes: bytes, audio_processor: "ProcessorMixin", audio_model: "PreTrainedModel"
    ) -> dict:

View on GitHub (pinned to a597f97485)

Solutions

1. Send 'model' as a plain text form field: data={'model': 'openai/whisper-large-v3'}
2. Ensure only 'file' is sent as a file part and every other field as text
3. Inspect the outgoing multipart body (e.g. curl -F model=openai/whisper-large-v3 -F file=@a.wav) to confirm part types

Example fix

# before
requests.post(url, files={'file': fh, 'model': ('model.txt', b'whisper')})
# after
requests.post(url, files={'file': fh}, data={'model': 'openai/whisper-large-v3'})

assert isinstance(model_id, str), 'model must be a plain string form field'
resp = requests.post(url, files={'file': fh}, data={'model': model_id})

def is_model_field(v) -> bool:
    return isinstance(v, str) and len(v) > 0  # not a tuple/Blob file part

if resp.status_code == 422 and 'model name as string' in resp.text:
    raise ValueError("send 'model' as a text form field (data=), not a file part") from None

When it happens

Trigger: Including 'model' as a file part (files={'model': ...}) instead of a form field; clients that serialize the model name into a Blob; multipart bodies where the model part carries a filename disposition making it an UploadFile.

Common situations: Frontend code that wraps every value in FormData.append(name, new Blob([...])) instead of plain strings; ported code from an API that accepted model files by upload.

Related errors

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

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