HKUDS/DeepTutor · error · ParserError

markitdown failed to convert {Path(source_path).name}: {exc}

Error message

markitdown failed to convert {Path(source_path).name}: {exc}

What it means

The MarkItDown conversion step raised an arbitrary exception, which the engine wraps as a ParserError naming the file. MarkItDown throws for unsupported extensions, unreadable/corrupt files, or missing optional converters (e.g. mammoth, pdfminer).

Source

Thrown at deeptutor/services/parsing/engines/markitdown/engine.py:89

        return ReadinessReport(ready=True)

    def parse(
        self,
        source_path: Path,
        workdir: Path,
        *,
        config: MarkItDownConfig,
        on_output: Optional[Callable[[str], None]] = None,
    ) -> None:
        from markitdown import MarkItDown

        if on_output:
            on_output(f"Converting {Path(source_path).name} via markitdown…")
        try:
            converter = MarkItDown()
            result = converter.convert(str(source_path))
        except Exception as exc:  # noqa: BLE001 - surface as a parser error
            raise ParserError(f"markitdown failed to convert {Path(source_path).name}: {exc}")

        text = getattr(result, "text_content", None) or getattr(result, "markdown", None) or ""
        stem = Path(source_path).stem
        (workdir / f"{stem}.md").write_text(str(text), encoding="utf-8")


__all__ = ["MarkItDownParser"]

View on GitHub (pinned to 3e82f13042)

Solutions

1. Inspect the wrapped exc to see MarkItDown's underlying message.
2. Confirm the file type is supported and the file is valid.
3. pip install -U 'markitdown[all]' to get every format converter.
4. Catch ParserError and fall back to another engine.

Example fix

// before
out = engine.parse(p)

// after
try:
    out = engine.parse(p)
except ParserError as e:
    out = txt_fallback(p)

def can_markitdown(p):
    return p.is_file() and p.suffix.lower() in {".pdf", ".docx", ".pptx", ".xlsx", ".html"}

try:
    engine.parse(p)
except ParserError:
    engine2.parse(p)

When it happens

Trigger: converter.convert(str(source_path)) raising — unsupported file type, empty/corrupt document, or MarkItDown installed without the extras needed for that format.

Common situations: Feeding exotic formats (old .doc, ODF) without extras installed; corrupted Office/PDF files; MarkItDown version change altering supported formats.

Related errors

• LiteParse failed to convert {source_path.name}: {exc}
• MinerU archive exceeds the size limit.
• Transcription response had no `text` field.

AI-assisted analysis of HKUDS/DeepTutor@3e82f13042 (2026-08-27). Data as JSON: /api/errors/3638ef374e35fd30. Report an issue: GitHub.