{"record":{"id":"46e0d81470278c1e","repo":"microsoft/markitdown","slug":"contentunderstandingconverter-requires-the-optiona","errorCode":null,"errorMessage":"ContentUnderstandingConverter requires the optional dependency [az-content-understanding] (or [all]) to be installed. E.g., `pip install 'markitdown[az-content-understanding]'`","messagePattern":"ContentUnderstandingConverter requires the optional dependency \\[az-content-understanding\\] \\(or \\[all\\]\\) to be installed\\. E\\.g\\., `pip install 'markitdown\\[az-content-understanding\\]'`","errorType":"exception","errorClass":"MissingDependencyException","httpStatus":null,"severity":"error","filePath":"packages/markitdown/src/markitdown/converters/_cu_converter.py","lineNumber":474,"sourceCode":"        \"\"\"Initialize the Content Understanding converter.\n\n        Args:\n            endpoint: CU resource endpoint URL.\n            credential: Explicit credential. If None, falls back to\n                AZURE_API_KEY env var, then DefaultAzureCredential.\n            analyzer_id: Custom analyzer for compatible file types.\n                When set, the converter checks the analyzer's base modality\n                (via get_analyzer() at init) and routes only compatible\n                file types to it. Incompatible modalities auto-route to\n                default prebuilts. If None, auto-selects by extension/MIME.\n            file_types: Which file types to handle. If None, uses the\n                default set (all supported formats).\n        \"\"\"\n        super().__init__()\n\n        # Raise if dependencies are missing\n        if _dependency_exc_info is not None:\n            raise MissingDependencyException(\n                \"ContentUnderstandingConverter requires the optional dependency \"\n                \"[az-content-understanding] (or [all]) to be installed. \"\n                \"E.g., `pip install 'markitdown[az-content-understanding]'`\"\n            ) from _dependency_exc_info[\n                1\n            ].with_traceback(  # type: ignore[union-attr]\n                _dependency_exc_info[2]\n            )\n\n        self._file_types = file_types if file_types is not None else _ALL_FILE_TYPES\n        self._analyzer_id = analyzer_id\n        self._analyzer_modality: Optional[str] = None\n\n        # Resolve credential\n        if credential is None:\n            api_key = os.environ.get(\"AZURE_API_KEY\")\n            if api_key is not None:\n                credential = AzureKeyCredential(api_key)","sourceCodeStart":456,"sourceCodeEnd":492,"githubUrl":"https://github.com/microsoft/markitdown/blob/fd239d5d2be43d9b68329730206b9312c7d5a388/packages/markitdown/src/markitdown/converters/_cu_converter.py#L456-L492","documentation":"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.","triggerScenarios":"from markitdown.converters import ContentUnderstandingConverter; ContentUnderstandingConverter(...) in an environment where azure-ai-contentsafety / azure-identity (the [az-content-understanding] extra) are absent.","commonSituations":"Deploying code that optionally imports this converter without guarding the import, or installing plain 'markitdown' when the app path requires Azure features.","solutions":["pip install 'markitdown[az-content-understanding]' or 'markitdown[all]'","Verify the SDK imports: python -c \"from azure.ai.contentsafety import ContentSafetyClient\" (or the CU client used by the converter)","If installing the extra did not help, read the chained ImportError — it may point to a broken transitive dependency"],"exampleFix":"# before\npip install markitdown\nContentUnderstandingConverter()  # MissingDependencyException\n\n# after\npip install 'markitdown[az-content-understanding]'\nContentUnderstandingConverter()","handlingStrategy":"try-catch","validationCode":"import importlib.util\n\nCAN_USE_CU = importlib.util.find_spec(\"azure\") is not None  # probe the SDK package","typeGuard":null,"tryCatchPattern":"from markitdown import MissingDependencyException\n\ntry:\n    from markitdown.converters import ContentUnderstandingConverter\n    conv = ContentUnderstandingConverter()\nexcept (ImportError, MissingDependencyException) as e:\n    log.warning(\"CU converter unavailable: %s\", e)\n    conv = None  # degrade to default converters","preventionTips":["Declare 'markitdown[az-content-understanding]' in environments that use Azure CU","Guard optional converter imports so missing extras degrade instead of crashing the app"],"tags":["missing-dependency","azure","content-understanding","installation"],"backgroundTag":null,"analyzedSha":"fd239d5d2be43d9b68329730206b9312c7d5a388","analyzedAt":"2026-08-14T15:47:51.745Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}