microsoft/markitdown · error · MissingDependencyException

ContentUnderstandingConverter requires the optional dependen

Error message

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

What it means

ContentUnderstandingConverter's __init__ probes for the Azure Content Understanding SDK at import time and stores any ImportError in _dependency_exc_info. Constructing the converter without the SDK installed immediately raises MissingDependencyException naming the [az-content-understanding] extra, with the original ImportError chained as cause. Unlike lazily-failing converters, this one fails fast at construction because it is only instantiated on explicit request.

Source

Thrown at packages/markitdown/src/markitdown/converters/_cu_converter.py:474

        """Initialize the Content Understanding converter.

        Args:
            endpoint: CU resource endpoint URL.
            credential: Explicit credential. If None, falls back to
                AZURE_API_KEY env var, then DefaultAzureCredential.
            analyzer_id: Custom analyzer for compatible file types.
                When set, the converter checks the analyzer's base modality
                (via get_analyzer() at init) and routes only compatible
                file types to it. Incompatible modalities auto-route to
                default prebuilts. If None, auto-selects by extension/MIME.
            file_types: Which file types to handle. If None, uses the
                default set (all supported formats).
        """
        super().__init__()

        # Raise if dependencies are missing
        if _dependency_exc_info is not None:
            raise MissingDependencyException(
                "ContentUnderstandingConverter requires the optional dependency "
                "[az-content-understanding] (or [all]) to be installed. "
                "E.g., `pip install 'markitdown[az-content-understanding]'`"
            ) from _dependency_exc_info[
                1
            ].with_traceback(  # type: ignore[union-attr]
                _dependency_exc_info[2]
            )

        self._file_types = file_types if file_types is not None else _ALL_FILE_TYPES
        self._analyzer_id = analyzer_id
        self._analyzer_modality: Optional[str] = None

        # Resolve credential
        if credential is None:
            api_key = os.environ.get("AZURE_API_KEY")
            if api_key is not None:
                credential = AzureKeyCredential(api_key)

View on GitHub (pinned to fd239d5d2b)

Solutions

1. pip install 'markitdown[az-content-understanding]' or 'markitdown[all]'
2. Verify the SDK imports: python -c "from azure.ai.contentsafety import ContentSafetyClient" (or the CU client used by the converter)
3. If installing the extra did not help, read the chained ImportError — it may point to a broken transitive dependency

Example fix

# before
pip install markitdown
ContentUnderstandingConverter()  # MissingDependencyException

# after
pip install 'markitdown[az-content-understanding]'
ContentUnderstandingConverter()

import importlib.util

CAN_USE_CU = importlib.util.find_spec("azure") is not None  # probe the SDK package

from markitdown import MissingDependencyException

try:
    from markitdown.converters import ContentUnderstandingConverter
    conv = ContentUnderstandingConverter()
except (ImportError, MissingDependencyException) as e:
    log.warning("CU converter unavailable: %s", e)
    conv = None  # degrade to default converters

When it happens

Trigger: from markitdown.converters import ContentUnderstandingConverter; ContentUnderstandingConverter(...) in an environment where azure-ai-contentsafety / azure-identity (the [az-content-understanding] extra) are absent.

Common situations: Deploying code that optionally imports this converter without guarding the import, or installing plain 'markitdown' when the app path requires Azure features.

Related errors

• DocumentIntelligenceConverter requires the optional dependen
• {converter} recognized the input as a potential {extension}
• {converter} recognized the input as a potential {extension}
• {converter} recognized the input as a potential {extension}
• {converter} recognized the input as a potential {extension}

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