microsoft/markitdown · error · ValueError

Unsupported file type for Content Understanding conversion.

Error message

Unsupported file type for Content Understanding conversion.

What it means

ContentUnderstandingConverter.convert() starts by detecting the file type from stream_info via _detect_file_type(), which maps a lowercase extension (or MIME type) through _EXTENSION_MAP, filtered by the converter's file_types set. A None result — no mapping or excluded by file_types — raises this ValueError before any Azure call is made. Note accepts() normally prevents reaching convert() with unsupported types, so this guard fires mainly when converters are invoked directly or registrations are customized.

Source

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

        file_stream: BinaryIO,
        stream_info: StreamInfo,
        **kwargs: Any,
    ) -> bool:
        """Return True if the file type is in the configured set."""
        return _detect_file_type(stream_info, self._file_types) is not None

    def convert(
        self,
        file_stream: BinaryIO,
        stream_info: StreamInfo,
        **kwargs: Any,
    ) -> DocumentConverterResult:
        """Convert the file using CU and return Markdown with YAML front matter."""

        # 1. Determine analyzer_id (smart routing: check modality)
        file_type = _detect_file_type(stream_info, self._file_types)
        if file_type is None:
            raise ValueError(
                "Unsupported file type for Content Understanding conversion."
            )
        file_modality = _get_modality(file_type)

        if (
            self._analyzer_id is not None
            and self._analyzer_modality is not None
            and _is_analyzer_compatible(file_modality, self._analyzer_modality)
        ):
            analyzer_id = self._analyzer_id
        else:
            analyzer_id = _PREBUILT_ANALYZERS.get(
                file_modality, "prebuilt-documentSearch"
            )

        # 2. Read file bytes and determine MIME type
        file_bytes = file_stream.read()
        content_type = _content_type_for(file_type, stream_info.mimetype)

View on GitHub (pinned to fd239d5d2b)

Solutions

Pass explicit stream_info with a supported extension/mimetype (e.g. StreamInfo(extension='.pdf', mimetype='application/pdf'))
Widen or omit the file_types argument so the default full set applies
Rename/pre-convert files whose extension does not reflect content
Route through md.convert()/md.convert_stream() so accepts() filtering happens first

Example fix

# before
conv = ContentUnderstandingConverter(file_types=[ContentUnderstandingFileType.DOCX])
conv.convert(s, StreamInfo(extension=".pdf"))  # ValueError

# after
conv = ContentUnderstandingConverter()  # default: all supported types
conv.convert(s, StreamInfo(extension=".pdf", mimetype="application/pdf"))

Defensive patterns

Strategy: validation

Validate before calling

from markitdown.converters._cu_converter import _EXTENSION_MAP

def cu_supports(stream_info) -> bool:
    ext = (stream_info.extension or "").lower()
    return ext in _EXTENSION_MAP

Try / catch

try:
    result = cu_converter.convert(stream, stream_info)
except ValueError as e:
    if "Unsupported file type" in str(e):
        log.info("CU cannot handle %s; routing to default converters", stream_info.extension)
        result = md.convert(stream, stream_info=stream_info)
    else:
        raise

Prevention

Route files through MarkItDown.dispatch so accepts() filters unsupported types before convert()
When narrowing file_types, document the resulting accepted extensions and enforce them upstream
Always supply both extension and mimetype in StreamInfo for in-memory streams

When it happens

Trigger: Calling cu_converter.convert(stream, StreamInfo(extension='.xyz')) directly, passing a supported extension that was excluded via the file_types constructor argument, or a stream_info with neither extension nor a recognized mimetype.

Common situations: Constructing ContentUnderstandingConverter(file_types=[...]) too narrowly, direct converter invocation in tests/batches bypassing MarkItDown's dispatch, or files with missing/incorrect extensions.

Related errors

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