HKUDS/DeepTutor · error · MinerUError

MinerU reported done but returned no full_zip_url.

Error message

MinerU reported done but returned no full_zip_url.

What it means

The polling loop saw a terminal-success state but the entry had no full_zip_url, so there is nothing to download. Defensive check against an inconsistent API response.

Source

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

        if entry is not None:
            state = str(entry.get("state") or "").strip().lower()
            last_state = state or last_state
            if on_progress is not None:
                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."""

View on GitHub (pinned to 3e82f13042)

Solutions

1. Retry the parse job after a short delay — usually transient.
2. Log the raw entry JSON to confirm the field name/shape.
3. Check MinerU API docs/changelog if persistent.

try:
    parse_cloud(...)
except MinerUError as e:
    if "full_zip_url" in str(e):
        retry_with_backoff()

When it happens

Trigger: Polling /api/v4/extract results returning state=done with a missing/blank full_zip_url field.

Common situations: MinerU backend keeping results in cold storage briefly, partial response, or API contract change.

Related errors

• MinerU API did not return an upload URL (missing batch_id/fi
• MinerU API returned an unexpected (non-JSON) response.
• MinerU cloud mode is selected but no API token is configured
• PDF file not found: {pdf_path}
• Failed to upload PDF to MinerU: {exc}

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