microsoft/markitdown · error · ValueError

Unknown file type: {file_type}

Error message

Unknown file type: {file_type}

What it means

_get_modality() maps a ContentUnderstandingFileType to document/image/video/audio by set membership and raises ValueError for a value outside all four sets. It is a defensive internal invariant: file types reaching it come from _EXTENSION_MAP, which is built from those sets, so via the public API this fires only if the internal tables drift out of sync (e.g. a custom build adds a type to the map without a modality set).

Source

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

    "video": "prebuilt-videoSearch",
    "audio": "prebuilt-audioSearch",
}

# All supported file types (default set when file_types is None)
_ALL_FILE_TYPES = list(ContentUnderstandingFileType)


def _get_modality(file_type: ContentUnderstandingFileType) -> str:
    """Get the modality category for a file type."""
    if file_type in _DOCUMENT_TYPES:
        return "document"
    elif file_type in _IMAGE_TYPES:
        return "image"
    elif file_type in _VIDEO_TYPES:
        return "video"
    elif file_type in _AUDIO_TYPES:
        return "audio"
    raise ValueError(f"Unknown file type: {file_type}")


def _detect_file_type(
    stream_info: StreamInfo,
    file_types: Optional[List[ContentUnderstandingFileType]] = None,
) -> Optional[ContentUnderstandingFileType]:
    """Detect a supported CU file type from extension or MIME type."""
    allowed = set(file_types) if file_types is not None else None

    extension = (stream_info.extension or "").lower()
    file_type = _EXTENSION_MAP.get(extension)
    if file_type is not None and (allowed is None or file_type in allowed):
        return file_type

    mimetype = _clean_mime_type(stream_info.mimetype)
    if not mimetype:
        return None

View on GitHub (pinned to fd239d5d2b)

Solutions

1. Ensure any custom file type is added to exactly one of the four modality sets alongside _EXTENSION_MAP
2. Reinstall matching versions: pip install --force-reinstall markitdown to eliminate mixed-build skew
3. If you extended file_types, verify every enum member you pass exists in the supported modality sets

Example fix

# before (custom build)
_EXTENSION_MAP['.xyz'] = ContentUnderstandingFileType.MY_TYPE  # later: ValueError in _get_modality

# after
_EXTENSION_MAP['.xyz'] = ContentUnderstandingFileType.MY_TYPE
_DOCUMENT_TYPES.add(ContentUnderstandingFileType.MY_TYPE)

from markitdown.converters._cu_converter import (_DOCUMENT_TYPES, _IMAGE_TYPES, _VIDEO_TYPES, _AUDIO_TYPES)

ALL_KNOWN = _DOCUMENT_TYPES | _IMAGE_TYPES | _VIDEO_TYPES | _AUDIO_TYPES

def modality_known(file_type) -> bool:
    return file_type in ALL_KNOWN

try:
    modality = _get_modality(file_type)
except ValueError:
    log.error("file type %s registered without a modality set", file_type)
    raise

When it happens

Trigger: Maintainers adding a new entry to _EXTENSION_MAP/_ALL_FILE_TYPES without registering it in _DOCUMENT_TYPES/_IMAGE_TYPES/_VIDEO_TYPES/_AUDIO_TYPES; or monkey-patched file_types lists injecting an unknown enum value.

Common situations: Forking/extending the CU converter with custom file types, or version skew after a partial upgrade where the enum and the converter tables come from different builds.

Related errors

• Failed to resolve analyzer '{analyzer_id}': {exc}
• ContentUnderstandingConverter requires the optional dependen
• Unsupported file type for Content Understanding conversion.
• DocumentIntelligenceConverter requires the optional dependen

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