{"record":{"id":"2abb03d836e041ad","repo":"microsoft/markitdown","slug":"documentintelligenceconverter-requires-the-optiona","errorCode":null,"errorMessage":"DocumentIntelligenceConverter requires the optional dependency [az-doc-intel] (or [all]) to be installed. E.g., `pip install 'markitdown[az-doc-intel]'`","messagePattern":"DocumentIntelligenceConverter requires the optional dependency \\[az-doc-intel\\] \\(or \\[all\\]\\) to be installed\\. E\\.g\\., `pip install 'markitdown\\[az-doc-intel\\]'`","errorType":"exception","errorClass":"MissingDependencyException","httpStatus":null,"severity":"error","filePath":"packages/markitdown/src/markitdown/converters/_doc_intel_converter.py","lineNumber":167,"sourceCode":"    ):\n        \"\"\"\n        Initialize the DocumentIntelligenceConverter.\n\n        Args:\n            endpoint (str): The endpoint for the Document Intelligence service.\n            api_version (str): The API version to use. Defaults to \"2024-07-31-preview\".\n            credential (AzureKeyCredential | TokenCredential | None): The credential to use for authentication.\n            file_types (List[DocumentIntelligenceFileType]): The file types to accept. Defaults to all supported file types.\n        \"\"\"\n\n        super().__init__()\n        self._file_types = file_types\n\n        # Raise an error if the dependencies are not available.\n        # This is different than other converters since this one isn't even instantiated\n        # unless explicitly requested.\n        if _dependency_exc_info is not None:\n            raise MissingDependencyException(\n                \"DocumentIntelligenceConverter requires the optional dependency [az-doc-intel] (or [all]) to be installed. E.g., `pip install 'markitdown[az-doc-intel]'`\"\n            ) from _dependency_exc_info[\n                1\n            ].with_traceback(  # type: ignore[union-attr]\n                _dependency_exc_info[2]\n            )\n\n        if credential is None:\n            if os.environ.get(\"AZURE_API_KEY\") is None:\n                credential = DefaultAzureCredential()\n            else:\n                credential = AzureKeyCredential(os.environ[\"AZURE_API_KEY\"])\n\n        self.endpoint = endpoint\n        self.api_version = api_version\n        self.doc_intel_client = DocumentIntelligenceClient(\n            endpoint=self.endpoint,\n            api_version=self.api_version,","sourceCodeStart":149,"sourceCodeEnd":185,"githubUrl":"https://github.com/microsoft/markitdown/blob/fd239d5d2be43d9b68329730206b9312c7d5a388/packages/markitdown/src/markitdown/converters/_doc_intel_converter.py#L149-L185","documentation":"DocumentIntelligenceConverter stores the ImportError raised while importing the Azure Document Intelligence SDK and, in __init__, immediately raises MissingDependencyException naming the [az-doc-intel] extra with the original ImportError chained. The comment in the source notes this converter is only instantiated when explicitly requested, so it fails at construction time rather than at convert() time.","triggerScenarios":"from markitdown.converters import DocumentIntelligenceConverter; DocumentIntelligenceConverter(endpoint=...) without azure-ai-documentintelligence / azure-identity installed.","commonSituations":"Optional Azure code paths in a service that imports the converter eagerly, or environments where only core markitdown was installed.","solutions":["pip install 'markitdown[az-doc-intel]' or 'markitdown[all]' in the runtime environment","Verify: python -c \"import azure.ai.documentintelligence\"","If already installed, inspect the chained ImportError for the real broken transitive dependency and reinstall it"],"exampleFix":"# before\npip install markitdown\nDocumentIntelligenceConverter(endpoint=...)  # MissingDependencyException\n\n# after\npip install 'markitdown[az-doc-intel]'\nDocumentIntelligenceConverter(endpoint=...)","handlingStrategy":"try-catch","validationCode":"import importlib.util\n\nCAN_USE_DOC_INTEL = importlib.util.find_spec(\"azure\") is not None  # probe azure SDK presence","typeGuard":null,"tryCatchPattern":"from markitdown import MissingDependencyException\n\ntry:\n    conv = DocumentIntelligenceConverter(endpoint=endpoint)\nexcept MissingDependencyException as e:\n    log.warning(\"Doc Intel extra missing: %s\", e)\n    conv = None  # fall back to local converters","preventionTips":["Install 'markitdown[az-doc-intel]' wherever the converter is imported","Construct the converter inside a guarded factory so a missing extra disables the feature, not the app"],"tags":["missing-dependency","azure","document-intelligence","installation"],"backgroundTag":null,"analyzedSha":"fd239d5d2be43d9b68329730206b9312c7d5a388","analyzedAt":"2026-08-14T15:47:51.745Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}