HKUDS/DeepTutor · error · MinerUError

Failed to download MinerU result archive: {exc}

Error message

Failed to download MinerU result archive: {exc}

What it means

Downloading the finished result archive from the signed full_zip_url failed at the HTTP layer (status error, timeout, or connection issue).

Source

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

    body: dict[str, object] = {
        "files": [{"name": "connectivity-check.pdf", "is_ocr": False}],
        "model_version": config.model_version,
        "enable_formula": config.enable_formula,
        "enable_table": config.enable_table,
    }
    if config.api_language:
        body["language"] = config.api_language
    with httpx.Client(base_url=base_url, headers={"Accept": "application/json"}) as client:
        _post_json(client, "/api/v4/file-urls/batch", body, key_pool)


def _download(zip_url: str) -> bytes:
    try:
        response = httpx.get(zip_url, timeout=_DOWNLOAD_TIMEOUT_SECONDS, follow_redirects=True)
        response.raise_for_status()
        return response.content
    except httpx.HTTPError as exc:
        raise MinerUError(f"Failed to download MinerU result archive: {exc}") from exc


# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------


def _match_entry(results: list, file_name: str) -> dict | None:
    """Pick our file's result row. Single-file batch → first row is ours, but
    match on ``file_name`` when present to be safe."""
    rows = [r for r in results if isinstance(r, dict)]
    if not rows:
        return None
    for row in rows:
        if str(row.get("file_name") or "") == file_name:
            return row
    return rows[0]

View on GitHub (pinned to 3e82f13042)

Solutions

1. Retry the parse promptly so the zip URL is fresh.
2. Check network/proxy access to the result host.
3. Increase the download timeout constant for large results.

try:
    parse_cloud(...)
except MinerUError as e:
    if "download" in str(e).lower():
        time.sleep(5); parse_cloud(...)  # fresh zip URL

When it happens

Trigger: httpx.get(zip_url, follow_redirects=True) raising — expired link, storage outage, network drop, oversized archive hitting _DOWNLOAD_TIMEOUT_SECONDS.

Common situations: Result downloaded long after completion (expired URL), slow links for large artifact zips, proxy interference.

Related errors

• Failed to upload PDF to MinerU: {exc}
• MinerU API request failed: {exc}
• MinerU cloud mode is selected but no API token is configured
• PDF file not found: {pdf_path}
• MinerU API did not return an upload URL (missing batch_id/fi

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