{"record":{"id":"7c5c9c582e286e81","repo":"HKUDS/DeepTutor","slug":"mineru-failed-to-parse-the-document-err","errorCode":null,"errorMessage":"MinerU failed to parse the document: {err}","messagePattern":"MinerU failed to parse the document: (.+?)","errorType":"exception","errorClass":"MinerUError","httpStatus":null,"severity":"error","filePath":"deeptutor/services/parsing/engines/mineru/cloud.py","lineNumber":199,"sourceCode":"                progress = entry.get(\"extract_progress\") or {}\n                total_pages = progress.get(\"total_pages\")\n                report = f\"MinerU cloud: {state or 'queued'}\"\n                if total_pages:\n                    report += f\" ({progress.get('extracted_pages') or 0}/{total_pages} pages)\"\n                if report != last_report:\n                    last_report = report\n                    try:\n                        on_progress(report)\n                    except Exception:\n                        on_progress = None\n            if state == _TERMINAL_OK:\n                zip_url = str(entry.get(\"full_zip_url\") or \"\").strip()\n                if not zip_url:\n                    raise MinerUError(\"MinerU reported done but returned no full_zip_url.\")\n                return zip_url\n            if state == _TERMINAL_FAIL:\n                err = str(entry.get(\"err_msg\") or \"unknown error\")\n                raise MinerUError(f\"MinerU failed to parse the document: {err}\")\n        if time.monotonic() >= deadline:\n            raise MinerUError(\n                f\"MinerU parsing timed out after {int(timeout)}s \"\n                f\"(last state: {last_state or 'unknown'}).\"\n            )\n        time.sleep(poll_interval)\n\n\ndef verify_credentials(config: MinerUConfig) -> None:\n    \"\"\"Best-effort connectivity / token check for the Settings → MinerU \"Test\"\n    button. Requests an upload slot (which does not consume parsing quota and\n    is never followed by an upload, so it simply expires) and validates the\n    business code. Raises :class:`MinerUError` with a user-facing message on\n    any failure.\"\"\"\n    if not config.api_keys:\n        raise MinerUError(\"No API token configured.\")\n    base_url = config.api_base_url.rstrip(\"/\")\n    key_pool = KeyPool(config.api_keys)","sourceCodeStart":181,"sourceCodeEnd":217,"githubUrl":"https://github.com/HKUDS/DeepTutor/blob/3e82f130422a813cdd73c10b21a44e9325f5821a/deeptutor/services/parsing/engines/mineru/cloud.py#L181-L217","documentation":"The MinerU task reached a terminal failure state; err_msg from the API (or 'unknown error') is included. This is the server-side parse genuinely failing.","triggerScenarios":"Polling returns state in _TERMINAL_FAIL — corrupt/unreadable PDF, OCR failures on scanned garbage, server-side limits exceeded, or invalid parameters (model_version, enable_formula).","commonSituations":"Heavily scanned or encrypted PDFs, very large page counts, quota/model restrictions on the account.","solutions":["Open the PDF locally to confirm it's valid and not password-protected.","Read err_msg — it usually names the cause; adjust config (model_version, is_ocr) accordingly.","Try local mode or another engine for problematic PDFs.","Retry once for transient server failures."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"def pdf_likely_ok(p: Path) -> bool:\n    head = p.read_bytes()[:1024]\n    return head.startswith(b\"%PDF-\") and b\"/Encrypt\" not in head","typeGuard":null,"tryCatchPattern":"try:\n    parse_cloud(...)\nexcept MinerUError as e:\n    if \"failed to parse the document\" in str(e):\n        log_err_msg(e); run_local_or_other_engine(pdf)","preventionTips":["Pre-check PDFs are valid and unencrypted.","Capture err_msg for triage; adjust model_version/is_ocr per document type.","Keep a local-mode or alternative parser fallback."],"tags":["mineru","cloud","pdf","ocr"],"backgroundTag":"remote-processing-failed","analyzedSha":"3e82f130422a813cdd73c10b21a44e9325f5821a","analyzedAt":"2026-08-27T06:57:25.364Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}