HKUDS/DeepTutor · error · ParserError

LiteParse failed to convert {source_path.name}: {exc}

Error message

LiteParse failed to convert {source_path.name}: {exc}

What it means

LiteParse engine wrapper failed while converting a document, and the wrapper rethrows the underlying exception as a ParserError with the filename and cause. This is a catch-all: any exception from LiteParse(**kwargs).parse() (unsupported format, corrupt file, missing optional dependency) surfaces here.

Source

Thrown at deeptutor/services/parsing/engines/liteparse/engine.py:113

            "image_mode": config.image_mode,
            "extract_links": config.extract_links,
            "quiet": True,
            # A systemic OCR failure aborts the whole parse by default. Prefer
            # the natively recovered text over losing the document outright —
            # the ingestion pipeline treats a ParserError as "no content".
            "ocr_failure_fatal": False,
        }
        if config.extract_images:
            images_dir.mkdir(parents=True, exist_ok=True)
            kwargs["extract_images"] = True
            kwargs["image_output_dir"] = str(images_dir)
        if config.max_pages > 0:
            kwargs["max_pages"] = config.max_pages

        try:
            result = LiteParse(**kwargs).parse(str(source_path))
        except Exception as exc:  # noqa: BLE001 - surface as a parser error
            raise ParserError(f"LiteParse failed to convert {source_path.name}: {exc}") from exc

        markdown = str(getattr(result, "text", "") or "")
        if config.extract_images:
            markdown = self._portable_image_links(markdown, getattr(result, "images", None))
            # Drop the images dir if nothing was actually extracted, so the
            # cache loader doesn't report an empty asset_dir.
            if images_dir.is_dir() and not any(images_dir.iterdir()):
                images_dir.rmdir()

        (workdir / f"{source_path.stem}.md").write_text(markdown, encoding="utf-8")

    @staticmethod
    def _portable_image_links(markdown: str, images: Any) -> str:
        """Prefix links naming an extracted image with the ``images/`` dir.

        Only names LiteParse reports as extracted are rewritten, so a link the
        document itself carried to an unrelated URL is left alone.
        """

View on GitHub (pinned to 3e82f13042)

Solutions

1. Check the chained cause (exc) in the traceback — the LiteParse exception names the real problem.
2. Verify the file opens in a native viewer and is a supported format.
3. Reinstall/upgrade LiteParse with the extras for that format (e.g. pip install -U liteparse[pdf]).
4. Wrap parse() in try/except ParserError and fall back to another parsing engine.
5. If max_pages is set, confirm it's valid for the file.

Example fix

// before
result = engine.parse(Path("doc.pdf"))

// after
try:
    result = engine.parse(Path("doc.pdf"))
except ParserError as e:
    logger.warning("liteparse failed: %s", e)
    result = fallback_engine.parse(Path("doc.pdf"))

from pathlib import Path
SUPPORTED = {".pdf", ".docx", ".pptx", ".html", ".md", ".txt"}
def can_liteparse(p: Path) -> bool:
    return p.is_file() and p.stat().st_size > 0 and p.suffix.lower() in SUPPORTED

try:
    result = engine.parse(path)
except ParserError as e:
    logger.warning("liteparse failed (%s); falling back", e)
    result = fallback.parse(path)

When it happens

Trigger: Calling engine.parse(source_path) on a file LiteParse cannot handle, a corrupted/truncated document, or a LiteParse install missing format-specific extras. Any non-zero config.max_pages is passed into kwargs before the failing call.

Common situations: Parsing an unsupported or zero-byte file, feeding a password-protected PDF, version drift between LiteParse and its optional dependencies, or bad kwargs built from config.

Related errors

• markitdown failed to convert {Path(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/585a7e456818bf3e. Report an issue: GitHub.