{"record":{"id":"abf57771858b12c5","repo":"huggingface/transformers","slug":"missing-librosa-dependency-for-audio-transcription","errorCode":null,"errorMessage":"Missing librosa dependency for audio transcription. Install with `pip install librosa`","messagePattern":"Missing librosa dependency for audio transcription\\. Install with `pip install librosa`","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"src/transformers/cli/serving/transcription.py","lineNumber":98,"sourceCode":"            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`\")\n        if not is_multipart_available():\n            raise ImportError(\n                \"Missing python-multipart dependency for file uploads. Install with `pip install python-multipart`\"\n            )\n\n        async with request.form() as form:\n            self._validate_request(set(form.keys()))\n            file_field = form[\"file\"]\n            if isinstance(file_field, str):\n                raise HTTPException(status_code=422, detail=\"Expected file upload, got string\")\n            file_bytes = await file_field.read()\n            model = form[\"model\"]\n            if not isinstance(model, str):\n                raise HTTPException(status_code=422, detail=\"Expected model name as string\")\n            stream = str(form.get(\"stream\", \"false\")).lower() == \"true\"\n\n        model_id_and_revision = self.model_manager.process_model_name(model)\n        audio_model, audio_processor = self.model_manager.load_model_and_processor(model_id_and_revision)","sourceCodeStart":80,"sourceCodeEnd":116,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/cli/serving/transcription.py#L80-L116","documentation":"An ImportError raised by the transcription handler when transformers.utils.import_utils.is_librosa_available() returns False. Loading and decoding arbitrary audio bytes into model inputs requires librosa, which is an optional dependency, so the server refuses transcription requests until it is installed. Because it is a plain ImportError (not HTTPException) it surfaces as a 500 unless mapped by exception handlers.","triggerScenarios":"POST /v1/audio/transcriptions on an environment where librosa is not installed: minimal Docker images, fresh venvs with only 'pip install transformers', or CI environments without the audio extra.","commonSituations":"Deploying the serving CLI in a slim container without the audio extra; upgrading transformers in an env where librosa was never present; audio dependencies being stripped by dependency resolvers.","solutions":["Install librosa in the serving environment: pip install librosa","Or install the audio extra so all audio deps arrive together: pip install 'transformers[audio]'","Add a startup health check that calls is_librosa_available() so the gap is caught before the first request"],"exampleFix":"# before\n$ pip install transformers fastapi uvicorn\n# after\n$ pip install 'transformers[audio]' librosa","handlingStrategy":"validation","validationCode":"from transformers.utils.import_utils import is_librosa_available\nif not is_librosa_available():\n    raise SystemExit('Install librosa (pip install transformers[audio]) before serving transcription')","typeGuard":null,"tryCatchPattern":"try:\n    resp = requests.post(url, files=form)\nexcept ImportError as e:\n    if 'librosa' in str(e):\n        subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'librosa'])\n        resp = requests.post(url, files=form)","preventionTips":["Install the audio extra in serving images: pip install 'transformers[audio]'","Run dependency availability checks at server startup, not at first request"],"tags":["dependency","audio","serving","importerror"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}