HKUDS/DeepTutor · error · MinerUError

MinerU failed to parse the document: {err}

Error message

MinerU failed to parse the document: {err}

What it means

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.

Source

Thrown at deeptutor/services/parsing/engines/mineru/cloud.py:199

                progress = entry.get("extract_progress") or {}
                total_pages = progress.get("total_pages")
                report = f"MinerU cloud: {state or 'queued'}"
                if total_pages:
                    report += f" ({progress.get('extracted_pages') or 0}/{total_pages} pages)"
                if report != last_report:
                    last_report = report
                    try:
                        on_progress(report)
                    except Exception:
                        on_progress = None
            if state == _TERMINAL_OK:
                zip_url = str(entry.get("full_zip_url") or "").strip()
                if not zip_url:
                    raise MinerUError("MinerU reported done but returned no full_zip_url.")
                return zip_url
            if state == _TERMINAL_FAIL:
                err = str(entry.get("err_msg") or "unknown error")
                raise MinerUError(f"MinerU failed to parse the document: {err}")
        if time.monotonic() >= deadline:
            raise MinerUError(
                f"MinerU parsing timed out after {int(timeout)}s "
                f"(last state: {last_state or 'unknown'})."
            )
        time.sleep(poll_interval)


def verify_credentials(config: MinerUConfig) -> None:
    """Best-effort connectivity / token check for the Settings → MinerU "Test"
    button. Requests an upload slot (which does not consume parsing quota and
    is never followed by an upload, so it simply expires) and validates the
    business code. Raises :class:`MinerUError` with a user-facing message on
    any failure."""
    if not config.api_keys:
        raise MinerUError("No API token configured.")
    base_url = config.api_base_url.rstrip("/")
    key_pool = KeyPool(config.api_keys)

View on GitHub (pinned to 3e82f13042)

Solutions

1. Open the PDF locally to confirm it's valid and not password-protected.
2. Read err_msg — it usually names the cause; adjust config (model_version, is_ocr) accordingly.
3. Try local mode or another engine for problematic PDFs.
4. Retry once for transient server failures.

def pdf_likely_ok(p: Path) -> bool:
    head = p.read_bytes()[:1024]
    return head.startswith(b"%PDF-") and b"/Encrypt" not in head

try:
    parse_cloud(...)
except MinerUError as e:
    if "failed to parse the document" in str(e):
        log_err_msg(e); run_local_or_other_engine(pdf)

When it happens

Trigger: 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).

Common situations: Heavily scanned or encrypted PDFs, very large page counts, quota/model restrictions on the account.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Local MinerU parsing failed. Ensure MinerU is installed (`pi
• Configured MinerU CLI path is not an executable file: {probe
• MinerU produced no output directory.
• MinerU cloud mode is selected but no API token is configured
• PDF file not found: {pdf_path}

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