{"record":{"id":"9821bdb3dd5670b7","repo":"docling-project/docling","slug":"asr-pipeline-requires-a-file-path-or-bytesio-strea","errorCode":null,"errorMessage":"ASR pipeline requires a file path or BytesIO stream, but got {type(path_or_stream)}","messagePattern":"ASR pipeline requires a file path or BytesIO stream, but got (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"docling/pipeline/asr_transcriber.py","lineNumber":303,"sourceCode":"\n    def run(self, conv_res: ConversionResult) -> ConversionResult:\n        # Access the file path from the backend, similar to other pipelines\n        path_or_stream = conv_res.input._backend.path_or_stream\n\n        # Handle both Path and BytesIO inputs\n        temp_file_path: Path | None = None\n\n        if isinstance(path_or_stream, BytesIO):\n            # For BytesIO, write to a temporary file (whisper needs a file path)\n            suffix = Path(conv_res.input.file.name).suffix or \".wav\"\n            with tempfile.NamedTemporaryFile(delete=False, suffix=suffix) as tmp_file:\n                tmp_file.write(path_or_stream.getvalue())\n                temp_file_path = Path(tmp_file.name)\n            audio_path = temp_file_path\n        elif isinstance(path_or_stream, Path):\n            audio_path = path_or_stream\n        else:\n            raise RuntimeError(\n                f\"ASR pipeline requires a file path or BytesIO stream, \"\n                f\"but got {type(path_or_stream)}\"\n            )\n\n        try:\n            if shutil.which(\"ffmpeg\") is None:\n                _log.error(MISSING_FFMPEG_MESSAGE)\n                conv_res.errors.append(\n                    ErrorItem(\n                        component_type=DoclingComponentType.PIPELINE,\n                        module_name=\"AsrPipeline\",\n                        error_message=MISSING_FFMPEG_MESSAGE,\n                    )\n                )\n                conv_res.status = ConversionStatus.FAILURE\n                return conv_res\n\n            conversation = self.transcribe(audio_path)","sourceCodeStart":285,"sourceCodeEnd":321,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/pipeline/asr_transcriber.py#L285-L321","documentation":"The native-whisper transcriber's run() only accepts input streams of type BytesIO or Path, because whisper.load_model/transcribe needs a real file path (BytesIO is spilled to a NamedTemporaryFile). Any other object (plain file object, str path, bytes) raises RuntimeError with the received type.","triggerScenarios":"Converting a document whose backend exposes path_or_stream as something other than BytesIO or pathlib.Path — e.g. passing a raw str filename to DocumentConverter, an opened file handle, or a custom InputDocument backend storing bytes.","commonSituations":"Calling DocumentConverter.convert('audio.mp3') with a string instead of Path('audio.mp3'); custom format backends that keep content as bytes or StringIO; wrappers that pass http response bodies directly.","solutions":["Wrap string paths in pathlib.Path before conversion: DocumentConverter().convert(Path('audio.mp3'))","Wrap raw bytes in io.BytesIO(bytes_payload) so the transcriber spills it to a temp file itself","For custom backends, make path_or_stream return Path or BytesIO"],"exampleFix":"# before\nconv = converter.convert('meeting.wav')   # str -> RuntimeError\n\n# after\nfrom pathlib import Path\nconv = converter.convert(Path('meeting.wav'))","handlingStrategy":"type-guard","validationCode":"from io import BytesIO\nfrom pathlib import Path\n\naudio = Path('meeting.wav') if isinstance(audio, str) else audio\nif not isinstance(audio, (Path, BytesIO)):\n    audio = BytesIO(audio) if isinstance(audio, (bytes, bytearray)) else Path(audio)","typeGuard":"from io import BytesIO\nfrom pathlib import Path\nfrom typing import Any\n\ndef is_asr_input(x: Any) -> bool:\n    return isinstance(x, (Path, BytesIO))","tryCatchPattern":null,"preventionTips":["Always convert() with pathlib.Path objects, never bare strings","Wrap in-memory bytes in io.BytesIO at the edge of your code","Standardize a to_asr_input() helper for all audio sources"],"tags":["asr","whisper","input-type","pathlib"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}