{"record":{"id":"585a7e456818bf3e","repo":"HKUDS/DeepTutor","slug":"liteparse-failed-to-convert-source-path-name-e","errorCode":null,"errorMessage":"LiteParse failed to convert {source_path.name}: {exc}","messagePattern":"LiteParse failed to convert (.+?): (.+?)","errorType":"exception","errorClass":"ParserError","httpStatus":null,"severity":"error","filePath":"deeptutor/services/parsing/engines/liteparse/engine.py","lineNumber":113,"sourceCode":"            \"image_mode\": config.image_mode,\n            \"extract_links\": config.extract_links,\n            \"quiet\": True,\n            # A systemic OCR failure aborts the whole parse by default. Prefer\n            # the natively recovered text over losing the document outright —\n            # the ingestion pipeline treats a ParserError as \"no content\".\n            \"ocr_failure_fatal\": False,\n        }\n        if config.extract_images:\n            images_dir.mkdir(parents=True, exist_ok=True)\n            kwargs[\"extract_images\"] = True\n            kwargs[\"image_output_dir\"] = str(images_dir)\n        if config.max_pages > 0:\n            kwargs[\"max_pages\"] = config.max_pages\n\n        try:\n            result = LiteParse(**kwargs).parse(str(source_path))\n        except Exception as exc:  # noqa: BLE001 - surface as a parser error\n            raise ParserError(f\"LiteParse failed to convert {source_path.name}: {exc}\") from exc\n\n        markdown = str(getattr(result, \"text\", \"\") or \"\")\n        if config.extract_images:\n            markdown = self._portable_image_links(markdown, getattr(result, \"images\", None))\n            # Drop the images dir if nothing was actually extracted, so the\n            # cache loader doesn't report an empty asset_dir.\n            if images_dir.is_dir() and not any(images_dir.iterdir()):\n                images_dir.rmdir()\n\n        (workdir / f\"{source_path.stem}.md\").write_text(markdown, encoding=\"utf-8\")\n\n    @staticmethod\n    def _portable_image_links(markdown: str, images: Any) -> str:\n        \"\"\"Prefix links naming an extracted image with the ``images/`` dir.\n\n        Only names LiteParse reports as extracted are rewritten, so a link the\n        document itself carried to an unrelated URL is left alone.\n        \"\"\"","sourceCodeStart":95,"sourceCodeEnd":131,"githubUrl":"https://github.com/HKUDS/DeepTutor/blob/3e82f130422a813cdd73c10b21a44e9325f5821a/deeptutor/services/parsing/engines/liteparse/engine.py#L95-L131","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the chained cause (exc) in the traceback — the LiteParse exception names the real problem.","Verify the file opens in a native viewer and is a supported format.","Reinstall/upgrade LiteParse with the extras for that format (e.g. pip install -U liteparse[pdf]).","Wrap parse() in try/except ParserError and fall back to another parsing engine.","If max_pages is set, confirm it's valid for the file."],"exampleFix":"// before\nresult = engine.parse(Path(\"doc.pdf\"))\n\n// after\ntry:\n    result = engine.parse(Path(\"doc.pdf\"))\nexcept ParserError as e:\n    logger.warning(\"liteparse failed: %s\", e)\n    result = fallback_engine.parse(Path(\"doc.pdf\"))","handlingStrategy":"fallback","validationCode":"from pathlib import Path\nSUPPORTED = {\".pdf\", \".docx\", \".pptx\", \".html\", \".md\", \".txt\"}\ndef can_liteparse(p: Path) -> bool:\n    return p.is_file() and p.stat().st_size > 0 and p.suffix.lower() in SUPPORTED","typeGuard":null,"tryCatchPattern":"try:\n    result = engine.parse(path)\nexcept ParserError as e:\n    logger.warning(\"liteparse failed (%s); falling back\", e)\n    result = fallback.parse(path)","preventionTips":["Validate file exists, is non-empty, and has a supported extension before parsing.","Keep LiteParse and its format extras up to date.","Always keep a fallback engine configured."],"tags":["parsing","liteparse","document-conversion"],"backgroundTag":"document-parse-failed","analyzedSha":"3e82f130422a813cdd73c10b21a44e9325f5821a","analyzedAt":"2026-08-27T06:57:25.364Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}