[Bug]: MinerU API integration fails with "Missing output file" despite successful API parsing

[lvwenbo567-art]

Self Checks

• I have searched for existing issues search for existing issues, including closed ones.
• I confirm that I am using English to submit this report (Language Policy).
• Non-english title submitions will be closed directly ( 非英文标题的提交将会被直接关闭 ) (Language Policy).
• Please do not modify this template :) and fill in all the required fields.

RAGFlow workspace code commit ID

none

RAGFlow image version

v0.24.0

Other environment information

**Environment:**
* **RAGFlow Version:** v0.24.0 (Docker deployment)
* **MinerU Version:** (Installed via uv inside `/ragflow/uv_tools/.venv`)
* **OS/Deployment:** Docker (Local/Offline deployment)

Actual behavior

Description:
When configuring MinerU as the chunking method via the API backend (MINERU_APISERVER), RAGFlow successfully sends the PDF, and MinerU processes it and returns a ZIP file. However, RAGFlow fails to locate the expected JSON output file inside the unzipped directory, throwing a Missing output file error. This occurs even with purely English, simple filenames (e.g., Pre.pdf).

Additionally, after the file matching fails, RAGFlow incorrectly falls back to executing the local CLI command, which causes a misleading [ERROR]MinerU not found log because the mineru executable is inside the uv_tools virtual environment rather than the global $PATH.

Root Cause Analysis & Suggestions:

1. Output File Naming Mismatch: It appears the latest version of MinerU has changed its ZIP output structure or JSON naming conventions. RAGFlow strictly expects <filename>_content_list.json, which no longer exists in the MinerU API response. RAGFlow's extraction logic (LLMBundle) needs to be updated to match the current MinerU output schema.
2. Fallback Mechanism Bug: If the API successfully returns a ZIP but RAGFlow fails to find the file, it shouldn't silently fall back to the local CLI mode. Furthermore, if CLI mode is intended as a fallback, RAGFlow should use the path defined in MINERU_EXECUTABLE rather than assuming mineru is in the global $PATH.

Expected behavior

Error Logs:

2026-04-02 20:02:54,676 INFO     98 [MinerU] Extract zip: zip_path=/tmp/mineru_pdf_mckn9b8v/Pre_auto_z5hagbcn.zip, extract_to=/tmp/mineru_pdf_mckn9b8v/Pre_auto_z5hagbcn, root_hint=Pre/
2026-04-02 20:02:54,689 INFO     98 [MinerU] Api completed successfully.
2026-04-02 20:02:54,690 INFO     98 [MinerU] Expected output files: Pre_content_list.json
2026-04-02 20:02:54,690 INFO     98 [MinerU] Searching output in: /tmp/mineru_pdf_mckn9b8v/Pre_auto_z5hagbcn
2026-04-02 20:02:54,692 ERROR    98 Failed to parse pdf via LLMBundle MinerU (Mineru): [MinerU] Missing output file, tried: /tmp/mineru_pdf_mckn9b8v/Pre_auto_z5hagbcn/Pre_content_list.json, /tmp/mineru_pdf_mckn9b8v/Pre_auto_z5hagbcn/Pre/Pre_content_list.json
2026-04-02 20:02:54,705 INFO     98 [ERROR]MinerU not found.

Steps to reproduce

**Steps to Reproduce:**
1. Deploy RAGFlow via Docker Compose.
2. Start the MinerU API server manually inside the container (`mineru-api --host 0.0.0.0 --port 8886`).
3. Set environment variables in `entrypoint.sh` or `.env`: `MINERU_APISERVER=http://127.0.0.1:8886`, `MINERU_BACKEND=pipeline`.
4. Upload a simple English PDF (e.g., `Pre.pdf`) and set the Chunk Method to `MinerU`.
5. Observe the parsing failure in the task execution logs.

Additional information

No response

[dosubot]

Hi @lvwenbo567-art! I'm Dosu and I’m helping the ragflow team.

This looks like it could be related to a few known issues with the MinerU API integration. Let me share what I found in the codebase:

Regarding the "Missing output file" error: The current code in deepdoc/parser/mineru_parser.py already implements a three-tier fallback search for the JSON output file — it tries the original filename, a sanitized filename, and a nested directory path [1]. However, depending on your MinerU version and backend, the actual ZIP structure may not match any of these candidates.

A very similar issue was reported and fixed previously — when using vlm-* backends, MinerU writes output to an /auto/ subdirectory, but RAGFlow was searching in /vlm/ instead [2]. This was fixed in PR #11623, which added multi-candidate directory fallback (vlm/ → method/ → auto/). Since you're on v0.24.0, you should already have this fix. Could you check what the actual directory structure inside the extracted ZIP looks like? Setting MINERU_DELETE_OUTPUT=0 will preserve the temp files for inspection.

Regarding the [ERROR]MinerU not found fallback: As of December 2025, CLI support was fully removed from the MinerU integration (PR #11977) — the code now calls _run_mineru_api() directly with no CLI fallback [3]. If you're seeing a MinerU not found log, it may be coming from a higher-level error handler rather than an actual CLI fallback attempt [4]. MINERU_EXECUTABLE is deprecated and unused in current versions [5].

One more thing to check: There's also a known API endpoint mismatch — newer MinerU versions expose /pdf_parse while RAGFlow hardcodes /file_parse . If you're running a recent MinerU build, this could also be a factor. Workarounds include using MinerU 2.6.x, patching the RAGFlow code to use /pdf_parse, or setting up an NGINX proxy.

To debug further, I'd suggest:

1. Set MINERU_DELETE_OUTPUT=0 and re-run the parse
2. Inspect the extracted ZIP contents at the path shown in the logs (/tmp/mineru_pdf_mckn9b8v/Pre_auto_z5hagbcn/) to see the actual file/directory structure
3. Share that structure here — it'll make it clear whether this is a naming mismatch, a backend subdirectory issue, or something else entirely

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}