{"record":{"id":"91c92d08f4844e39","repo":"microsoft/markitdown","slug":"converter-recognized-the-input-as-a-potential-e","errorCode":null,"errorMessage":"{converter} recognized the input as a potential {extension} file, but the dependencies needed to read {extension} files have not been installed. To resolve this error, include the optional dependency [{feature}] or [all] when installing MarkItDown. For example:\n\n* pip install 'markitdown[{feature}]'\n* pip install 'markitdown[all]'\n* pip install 'markitdown[{feature}, ...]'\n* etc.","messagePattern":"(.+?) recognized the input as a potential (.+?) file, but the dependencies needed to read (.+?) files have not been installed\\. To resolve this error, include the optional dependency \\[(.+?)\\] or \\[all\\] when installing MarkItDown\\. For example:\n\n\\* pip install 'markitdown\\[(.+?)\\]'\n\\* pip install 'markitdown\\[all\\]'\n\\* pip install 'markitdown\\[(.+?), \\.\\.\\.\\]'\n\\* etc\\.","errorType":"exception","errorClass":"MissingDependencyException","httpStatus":null,"severity":"error","filePath":"packages/markitdown-ocr/src/markitdown_ocr/_docx_converter_with_ocr.py","lineNumber":70,"sourceCode":"\n        if extension == \".docx\":\n            return True\n\n        if mimetype.startswith(\n            \"application/vnd.openxmlformats-officedocument.wordprocessingml\"\n        ):\n            return True\n\n        return False\n\n    def convert(\n        self,\n        file_stream: BinaryIO,\n        stream_info: StreamInfo,\n        **kwargs: Any,\n    ) -> DocumentConverterResult:\n        if _dependency_exc_info is not None:\n            raise MissingDependencyException(\n                MISSING_DEPENDENCY_MESSAGE.format(\n                    converter=type(self).__name__,\n                    extension=\".docx\",\n                    feature=\"docx\",\n                )\n            ) from _dependency_exc_info[1].with_traceback(\n                _dependency_exc_info[2]\n            )  # type: ignore[union-attr]\n\n        # Get OCR service if available (from kwargs or instance)\n        ocr_service: Optional[LLMVisionOCRService] = (\n            kwargs.get(\"ocr_service\") or self.ocr_service\n        )\n\n        if ocr_service:\n            # 1. Extract and OCR images — returns raw text per image\n            file_stream.seek(0)\n            image_ocr_map = self._extract_and_ocr_images(file_stream, ocr_service)","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/microsoft/markitdown/blob/fd239d5d2be43d9b68329730206b9312c7d5a388/packages/markitdown-ocr/src/markitdown_ocr/_docx_converter_with_ocr.py#L52-L88","documentation":"The OCR-enabled DocxConverterWithOCR in the markitdown-ocr plugin accepted a .docx stream, but the import of its required packages (e.g. mammoth / python-docx) failed at module load time. The stored import exception is re-raised as MissingDependencyException when convert() is called, with a message telling you exactly which pip extra to install. The traceback of the original ImportError is chained via 'from', so the root cause stays visible.","triggerScenarios":"Calling convert()/convert_stream() on a .docx file through DocxConverterWithOCR when 'mammoth' (the docx extra) is not installed in the active environment; e.g. pip install markitdown-ocr without extras, then converting a Word document with OCR enabled.","commonSituations":"Installing markitdown-ocr as a bare dependency in a service image, mixing virtual environments (converter registered in one env, deps in another), or a partial install where the OCR extras were pruned by a slim Docker build.","solutions":["pip install 'markitdown[docx]' (or pip install 'markitdown[all]') in the SAME environment that runs the OCR converter","If using markitdown-ocr separately, ensure its declared dependencies (mammoth, etc.) are installed: pip install markitdown-ocr[all]","Verify with: python -c \"import mammoth\" before re-running the conversion","Check the chained 'from' traceback in the exception to confirm which specific import failed"],"exampleFix":"# before\npip install markitdown-ocr\nmd.convert(\"doc.docx\")  # MissingDependencyException\n\n# after\npip install 'markitdown[docx]' 'markitdown[all]'\nmd.convert(\"doc.docx\")","handlingStrategy":"try-catch","validationCode":"import importlib.util\n\nprint(importlib.util.find_spec(\"mammoth\") is not None)","typeGuard":null,"tryCatchPattern":"from markitdown import MissingDependencyException\n\ntry:\n    result = md.convert(docx_stream, stream_info=StreamInfo(extension=\".docx\"))\nexcept MissingDependencyException as e:\n    log.error(\"OCR docx extras missing: %s\", e)\n    raise","preventionTips":["Pin 'markitdown[all]' (or at least [docx]) in requirements to ship every extra the OCR plugin needs","Add a startup probe that importlib-checks each optional dependency your pipeline uses","Run conversions in the same virtualenv where the converter classes were imported"],"tags":["missing-dependency","ocr","docx","installation"],"backgroundTag":null,"analyzedSha":"fd239d5d2be43d9b68329730206b9312c7d5a388","analyzedAt":"2026-08-14T15:47:51.745Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}