microsoft/markitdown · error · MissingDependencyException

DocumentIntelligenceConverter requires the optional dependen

Error message

DocumentIntelligenceConverter requires the optional dependency [az-doc-intel] (or [all]) to be installed. E.g., `pip install 'markitdown[az-doc-intel]'`

What it means

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.

Source

Thrown at packages/markitdown/src/markitdown/converters/_doc_intel_converter.py:167

    ):
        """
        Initialize the DocumentIntelligenceConverter.

        Args:
            endpoint (str): The endpoint for the Document Intelligence service.
            api_version (str): The API version to use. Defaults to "2024-07-31-preview".
            credential (AzureKeyCredential | TokenCredential | None): The credential to use for authentication.
            file_types (List[DocumentIntelligenceFileType]): The file types to accept. Defaults to all supported file types.
        """

        super().__init__()
        self._file_types = file_types

        # Raise an error if the dependencies are not available.
        # This is different than other converters since this one isn't even instantiated
        # unless explicitly requested.
        if _dependency_exc_info is not None:
            raise MissingDependencyException(
                "DocumentIntelligenceConverter requires the optional dependency [az-doc-intel] (or [all]) to be installed. E.g., `pip install 'markitdown[az-doc-intel]'`"
            ) from _dependency_exc_info[
                1
            ].with_traceback(  # type: ignore[union-attr]
                _dependency_exc_info[2]
            )

        if credential is None:
            if os.environ.get("AZURE_API_KEY") is None:
                credential = DefaultAzureCredential()
            else:
                credential = AzureKeyCredential(os.environ["AZURE_API_KEY"])

        self.endpoint = endpoint
        self.api_version = api_version
        self.doc_intel_client = DocumentIntelligenceClient(
            endpoint=self.endpoint,
            api_version=self.api_version,

View on GitHub (pinned to fd239d5d2b)

Solutions

  1. pip install 'markitdown[az-doc-intel]' or 'markitdown[all]' in the runtime environment
  2. Verify: python -c "import azure.ai.documentintelligence"
  3. If already installed, inspect the chained ImportError for the real broken transitive dependency and reinstall it

Example fix

# before
pip install markitdown
DocumentIntelligenceConverter(endpoint=...)  # MissingDependencyException

# after
pip install 'markitdown[az-doc-intel]'
DocumentIntelligenceConverter(endpoint=...)
Defensive patterns

Strategy: try-catch

Validate before calling

import importlib.util

CAN_USE_DOC_INTEL = importlib.util.find_spec("azure") is not None  # probe azure SDK presence

Try / catch

from markitdown import MissingDependencyException

try:
    conv = DocumentIntelligenceConverter(endpoint=endpoint)
except MissingDependencyException as e:
    log.warning("Doc Intel extra missing: %s", e)
    conv = None  # fall back to local converters

Prevention

When it happens

Trigger: from markitdown.converters import DocumentIntelligenceConverter; DocumentIntelligenceConverter(endpoint=...) without azure-ai-documentintelligence / azure-identity installed.

Common situations: Optional Azure code paths in a service that imports the converter eagerly, or environments where only core markitdown was installed.

Related errors

AI-assisted analysis of microsoft/markitdown@fd239d5d2b (2026-08-14). Data as JSON: /api/errors/2abb03d836e041ad. Report an issue: GitHub.