What causes "File conversion failed after {len(attempts)} attempts:" in microsoft/markitdown?

Iterate exc.attempts on FileConversionException — each entry holds the individual exception and converter traceback that pinpoints the real failure

microsoft/markitdown · error · FileConversionException

File conversion failed after {len(attempts)} attempts:

Error message

File conversion failed after {len(attempts)} attempts:

What it means

During _convert_stream, every registered converter whose accepts() returned True is tried; each converter that raises is recorded in failed_attempts with its traceback and the stream is seeked back. If at least one converter attempted and all failed, a FileConversionException is raised aggregating those attempts — the per-attempt exceptions are on the exception object, not in the message.

Source

Thrown at packages/markitdown/src/markitdown/_markitdown.py:649

                        failed_attempts.append(
                            FailedConversionAttempt(
                                converter=converter, exc_info=sys.exc_info()
                            )
                        )
                    finally:
                        file_stream.seek(cur_pos)

                if res is not None:
                    # Normalize the content
                    res.text_content = "\n".join(
                        [line.rstrip() for line in re.split(r"\r?\n", res.text_content)]
                    )
                    res.text_content = re.sub(r"\n{3,}", "\n\n", res.text_content)
                    return res

        # If we got this far without success, report any exceptions
        if len(failed_attempts) > 0:
            raise FileConversionException(attempts=failed_attempts)

        # Nothing can handle it!
        raise UnsupportedFormatException(
            "Could not convert stream to Markdown. No converter attempted a conversion, suggesting that the filetype is simply not supported."
        )

    def register_page_converter(self, converter: DocumentConverter) -> None:
        """DEPRECATED: Use register_converter instead."""
        warn(
            "register_page_converter is deprecated. Use register_converter instead.",
            DeprecationWarning,
        )
        self.register_converter(converter)

    def register_converter(
        self,
        converter: DocumentConverter,
        *,

View on GitHub (pinned to fd239d5d2b)

Solutions

Iterate exc.attempts on FileConversionException — each entry holds the individual exception and converter traceback that pinpoints the real failure
Verify the file opens in its native application; test integrity (e.g. python -c "import zipfile; zipfile.ZipFile('f.docx').testzip()")
Re-download or re-save the source file if truncated or renamed
If an attempt shows MissingDependencyException, install the matching extra

Example fix

# before
result = md.convert("broken.docx")  # FileConversionException(attempts=[...])

# after
from markitdown import FileConversionException
try:
    result = md.convert("broken.docx")
except FileConversionException as e:
    for att in e.attempts:
        print(att.converter, "->", att.error)

Defensive patterns

Strategy: try-catch

Validate before calling

import zipfile

def looks_like_valid_docx(path: str) -> bool:
    return zipfile.is_zipfile(path) and zipfile.ZipFile(path).testzip() is None

Try / catch

from markitdown import FileConversionException

try:
    result = md.convert(path)
except FileConversionException as e:
    for attempt in e.attempts:
        log.error("converter %s failed: %s", attempt.converter, attempt.error)
    # distinguish root cause: missing extra vs corrupt file, then route accordingly
    raise

Prevention

Check file size > 0 and zip integrity before submitting Office files
Log e.attempts — the aggregated wrapper alone hides the real cause
Install all needed extras up front so dependency failures never become attempts

When it happens

Trigger: A file whose extension makes converters claim it (e.g. .docx, .xlsx) but whose content is corrupt, truncated, password-protected, or actually a different format; or all claiming converters hit their own missing-dependency/parse errors during convert().

Common situations: Zero-byte or partially uploaded files, Office documents saved with encryption, files with a wrong extension (renamed .zip to .docx), or several converters failing on a malformed structure so no result is ever produced.

Related errors

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