{"record":{"id":"d6421a8e4a675210","repo":"microsoft/markitdown","slug":"converter-recognized-the-input-as-a-potential-e-d6421a","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/src/markitdown/converters/_docx_converter.py","lineNumber":66,"sourceCode":"\n        if extension in ACCEPTED_FILE_EXTENSIONS:\n            return True\n\n        for prefix in ACCEPTED_MIME_TYPE_PREFIXES:\n            if mimetype.startswith(prefix):\n                return True\n\n        return False\n\n    def convert(\n        self,\n        file_stream: BinaryIO,\n        stream_info: StreamInfo,\n        **kwargs: Any,  # Options to pass to the converter\n    ) -> DocumentConverterResult:\n        # Check: the dependencies\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[\n                1\n            ].with_traceback(  # type: ignore[union-attr]\n                _dependency_exc_info[2]\n            )\n\n        style_map = kwargs.get(\"style_map\", None)\n        pre_process_stream = pre_process_docx(file_stream)\n        return self._html_converter.convert_string(\n            mammoth.convert_to_html(pre_process_stream, style_map=style_map).value,\n            **kwargs,\n        )\n","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/microsoft/markitdown/blob/fd239d5d2be43d9b68329730206b9312c7d5a388/packages/markitdown/src/markitdown/converters/_docx_converter.py#L48-L84","documentation":"MarkItDown's DocxConverter raises MissingDependencyException when its convert() method is invoked but the optional libraries needed to parse .docx files (mammoth, and for style maps mammoth without python-docx conflicts) failed to import at module load time. The import failure is captured in _dependency_exc_info at package import, and convert() re-raises this formatted message with install instructions. It means the converter accepted the file (extension .docx or the docx mimetype) but the runtime environment lacks the 'docx' optional extra.","triggerScenarios":"Calling markitdown.convert() (or MarkItDown().convert()) on a stream whose StreamInfo has extension .docx or mimetype application/vnd.openxmlformats-officedocument.wordprocessingml.document, on an installation done via `pip install markitdown` without extras. Also triggered when mammoth is installed but broken (e.g. incompatible Python version, corrupted install), because any ImportError/ModuleNotFoundError captured at module import produces the same exception.","commonSituations":"Installing the base markitdown package only; using a minimal Docker/CI image that strips optional deps; a transitive dependency conflict that breaks the mammoth import; upgrading Python versions so a pinned mammoth wheel no longer imports.","solutions":["Install the docx extra: pip install 'markitdown[docx]'","Or install all converters at once: pip install 'markitdown[all]'","If the extra is already declared installed, verify the import directly: python -c \"import mammoth\" and reinstall (pip install --force-reinstall mammoth) to fix a broken environment","If you distribute an app embedding markitdown, declare markitdown[docx] in your own dependency metadata so users get it automatically"],"exampleFix":"# before\npip install markitdown\nmarkitdown document.docx  # MissingDependencyException\n\n# after\npip install 'markitdown[docx]'\nmarkitdown document.docx","handlingStrategy":"try-catch","validationCode":"from markitdown.converters._docx_converter import _dependency_exc_info\n\ndef can_convert_docx() -> bool:\n    return _dependency_exc_info is None","typeGuard":"def has_docx_support() -> bool:\n    \"\"\"True when the docx optional dependency imported successfully.\"\"\"\n    import markitdown.converters._docx_converter as m\n    return m._dependency_exc_info is None","tryCatchPattern":"from markitdown import MarkItDown, MissingDependencyException\n\ntry:\n    result = MarkItDown().convert(\"doc.docx\")\nexcept MissingDependencyException:\n    # surface an actionable message to the operator instead of crashing\n    logger.error(\"markitdown docx extra missing: pip install 'markitdown[docx]'\")\n    raise","preventionTips":["Install with explicit extras in requirements: markitdown[docx]","At startup, probe optional extras with _dependency_exc_info is None checks for every format you accept","Document which formats your deployment supports and reject others at the API boundary"],"tags":["dependencies","installation","docx","optional-extras"],"backgroundTag":null,"analyzedSha":"fd239d5d2be43d9b68329730206b9312c7d5a388","analyzedAt":"2026-08-14T15:47:51.745Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}