What causes "Failed to convert {file_path.name}: {e}" in PaddlePaddle/PaddleOCR?

Read the chained cause (e.__cause__) to find the real failure

PaddlePaddle/PaddleOCR · error · RuntimeError

Failed to convert {file_path.name}: {e}

Error message

Failed to convert {file_path.name}: {e}

What it means

RuntimeError raised by doc2md_convert as a catch-all wrapper when converter.convert_file raises anything other than FileNotFoundError, ValueError, or RuntimeError. The original exception is chained (from e) and the message names the offending file, preserving the root cause while normalizing the error type.

Source

Thrown at paddleocr/_doc2md/core.py:58

    Examples:
        >>> from paddleocr import doc2md_convert
        >>> result = doc2md_convert("report.docx")
        >>> print(result.markdown)
    """
    file_path = Path(source)

    if not file_path.exists():
        raise FileNotFoundError(f"File not found: {file_path}")

    converter = default_registry.get_converter(file_path)

    try:
        result = converter.convert_file(file_path, **kwargs)
    except Exception as e:
        if isinstance(e, (FileNotFoundError, ValueError, RuntimeError)):
            raise
        raise RuntimeError(f"Failed to convert {file_path.name}: {e}") from e

    if output:
        output_path = Path(output)
        output_path.parent.mkdir(parents=True, exist_ok=True)
        output_path.write_text(result.markdown, encoding="utf-8")
        if result.images:
            images_dir = output_path.parent / "images"
            images_dir.mkdir(exist_ok=True)
            for rel_path, img_bytes in result.images.items():
                img_file = output_path.parent / rel_path
                img_file.write_bytes(img_bytes)

    return result


def supported_formats() -> list[str]:
    """Return a list of supported file extensions."""
    return default_registry.supported_extensions()

View on GitHub (pinned to 2661c7c0ef)

Solutions

Read the chained cause (e.__cause__) to find the real failure
Open the file in its native app (Word/Excel/PowerPoint) to check for corruption or passwords
Isolate and skip the bad file, then report it for manual repair

Example fix

# before
for f in files:
    doc2md_convert(f)
# after
for f in files:
    try:
        doc2md_convert(f)
    except RuntimeError as e:
        logger.warning('skipped %s: %s (cause: %r)', f, e, e.__cause__)
        continue

Defensive patterns

Strategy: try-catch

Try / catch

try:
    result = doc2md_convert(path)
except RuntimeError as e:
    cause = e.__cause__
    log.error('conversion failed for %s: %s | cause=%r', path, e, cause)
    quarantine(path)  # move bad file aside, continue batch

Prevention

Always log e.__cause__; the wrapper hides the real exception type
Quarantine failing files in batch pipelines instead of aborting
Pre-validate that files open in their native format for untrusted inputs

When it happens

Trigger: A corrupted or password-protected Office file that makes python-docx/openpyxl/python-pptx throw a package-specific exception; XML parse errors inside a malformed .docx; unexpected KeyError/TypeError from exotic documents.

Common situations: Batch-ingesting untrusted user documents; partially downloaded or truncated files; documents with unusual OOXML structures.

Related errors

AI-assisted analysis of PaddlePaddle/PaddleOCR@2661c7c0ef (2026-08-14). Data as JSON: /api/errors/512589dc1dfc8bb6. Report an issue: GitHub.