Desktop Client Download Handling#
MinerU surfaces two download paths: a Gradio GUI (self-hosted, browser-based) and a standalone Electron desktop client. Both retrieve parsed results as a ZIP from a remote CDN (cdn-mineru.openxlab.org.cn) once the server reports state: 'done' with a full_zip_url, but their error-handling and directory-lifecycle behaviors differ.
Gradio GUI Download Flow#
The Gradio GUI download flow is coordinated across two files:
-
Event wiring —
app.py: For each supported format (e.g. Markdown, JSON, LaTeX), a button click triggers_download_request_handler, which returns a per-request token. The front end validates the token (guarding against stale requests), then calls the server-side download handler and finally triggers the browser-side delivery viacomplete. -
Server-side handler —
app.pylines 1360–1387:_download_handlervalidates the token'srun_idagainst the current result, callsrender_downloadto build the archive, and returns the file path plus a JSON receipt. Any exception is caught: the error message is embedded in the receipt andNoneis returned as the file path — no file is delivered. -
Browser-side delivery —
gradio_download.jslines 26–58: If the receipt contains an error or no file URL, the button is restored and an alert is displayed. The error message shown is exactlyreceipt.error— the string produced bystr(exc)in the handler. -
ZIP generation —
artifacts.pylines 363–457:render_downloadbuilds format-specific archives._write_archivewrites to aTemporaryDirectoryand atomically replaces the final ZIP only on success; a failed write leaves no partial artifact.
Output Directory Lifecycle#
Each parsing run creates a dedicated output directory tree via create_run_artifacts:
<output_root>/gradio/<stem>_<uuid>/
downloads/
source.<ext>
middle_json.json
...
The downloads/ directory and run root are created at parse-time, not download-time. Download failures in the Gradio GUI do not trigger any directory cleanup — the directory structure persists whether or not a ZIP download succeeds .
Known Issue: Desktop Client (Non-Gradio)#
Discussion #5622 documents a failure mode specific to the standalone desktop client (v0.14.1):
- Root cause: The CDN TLS certificate for
cdn-mineru.openxlab.org.cnexpired on 2026-10-02, causing all ZIP downloads to fail withError: certificate has expiredin the Electron main process. - User-visible symptom: Tasks show "下载失败 / 未知错误" ("download failed /unknown error"). The underlying error (
certificate has expired) is only visible in~/Library/Logs/MinerU/main.log. - Directory residue: Failed downloads leave empty output directories (
<filename>.pdf-<uuid>/) and empty temp directories (<temId>/) in the save path. The desktop client does not clean these up on failure, nor defers their creation until success. - No retry UI: There is no in-client retry entry point for failed downloads.
The reporter confirmed the CDN content is intact (curl with -k returns HTTP 200 and a valid ZIP), so the failure is purely a certificate validation issue.
Error Messages (i18n)#
User-facing download error strings are defined in i18n.py lines 98–101:
| Key | English | Chinese |
|---|---|---|
download_failed | {format} download failed: {error} | {format} 下载失败:{error} |
missing_download | No download file was received. Please try again. | 未获得下载文件,请重试。 |
stale_download | The parsing result has changed. Please download again. | 解析结果已变更,请重新下载。 |
In the Gradio GUI, {error} is populated with str(exc) from the server handler, so specific error details (e.g. SSL errors) are surfaced. In the standalone desktop client, only the generic "未知错误" is shown in the UI — the detailed error is logged to the Electron log file only .
Key Files#
| File | Role |
|---|---|
mineru/kit/gradio/app.py | Download event wiring, _download_handler, _download_request_handler |
mineru/resources/gradio_download.js | Browser-side token tracking, anchor-click delivery, error alert |
mineru/kit/gradio/artifacts.py | render_download, _write_archive, create_run_artifacts |
mineru/kit/gradio/i18n.py | User-facing error strings |
tests/unittest/test_kit_gradio_download.py | Unit tests for download receipts, stale-run rejection, format events |