# Troubleshooting MinerU Installation and Parser Issues in RAG-Anything: Complete Guide

> Resolve MinerU installation and parser issues in RAGAnything. Learn common fixes for missing binaries, version conflicts, and unsupported formats. Get your RAG pipeline running smoothly.

- Repository: [✨Data Intelligence Lab@HKU✨/RAG-Anything](https://github.com/HKUDS/RAG-Anything)
- Tags: how-to-guide
- Published: 2026-04-22

---

**The most common MinerU installation and parser issues in RAG-Anything stem from missing binaries, version incompatibility with MinerU 2.0 breaking changes, and unsupported keyword arguments or file formats.**

RAG-Anything is an open-source document parsing framework that integrates multiple back-ends including **MinerU**, **Docling**, and **PaddleOCR**. All parsers inherit from `raganything.parser.Parser`, but MinerU 2.0 is an external command-line tool that requires special handling. This guide walks through the codebase to identify and resolve the most frequent troubleshooting scenarios for MinerU installation and parser issues in RAG-Anything.

## How RAG-Anything Detects MinerU Installation

The `MineruParser.check_installation()` method in [`raganything/parser.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/parser.py) (lines 1317–1348) runs `mineru --version` in a subprocess. It returns `True` only if the command succeeds without errors.

```python
from raganything.parser import MineruParser

# Quick installation sanity check

if not MineruParser.check_installation():
    raise RuntimeError("MinerU not found – run: pip install -U 'mineru[core]'")
else:
    print("✅ MinerU is ready")

```

If this check returns `False`, the binary is either not installed or not on `PATH`. Install with:

```bash
pip install -U "mineru[core]"

```

The error message logged in lines 1345–1347 provides additional diagnostic information.

## Resolving MinerU 2.0 Breaking Changes

MinerU 2.0 introduced significant breaking changes compared to 1.x releases. The most impactful change for RAG-Anything troubleshooting: **MinerU 2.0 no longer bundles LibreOffice conversion for Office documents**.

Verify your version compatibility:

```bash
mineru --version

```

Ensure you are running a **2.x** release. If the command fails, reinstall with the latest pip package.

### Handling Office Documents Without Native Conversion

The header comment in [`parser.py`](https://github.com/HKUDS/RAG-Anything/blob/main/parser.py) lines 19–22 and the warning block in `parse_document()` document this limitation. You have two options:

**Option A:** Convert Office documents to PDF yourself before processing:

```bash

# Using LibreOffice command-line

soffice --headless --convert-to pdf input.docx

```

**Option B:** Use `DoclingParser` as your back-end, which still supports `.docx`, `.pptx`, and other formats natively:

```python
from raganything import RagAnything
from raganything.parser import DoclingParser

rag = RagAnything(doc_parser=DoclingParser())

```

## Debugging Parser Execution with Logs

All MinerU interactions are logged with the prefix `[MinerU]` using the standard Python `logging` module. Enable console logging to inspect subprocess output:

```python
import logging
logging.basicConfig(level=logging.INFO)

# Now parse a document and watch for [MinerU] prefixed lines

from raganything.parser import MineruParser
content = MineruParser().parse_document("document.pdf")

```

Look for lines like `[MinerU] Command executed successfully` or specific error messages indicating command failures.

## Fixing Unsupported Keyword Argument Errors

The `_run_mineru_command()` method in [`parser.py`](https://github.com/HKUDS/RAG-Anything/blob/main/parser.py) lines 704–708 validates that no unexpected keyword arguments are passed. Passing extra kwargs raises `TypeError`.

**Incorrect usage that triggers the error:**

```python

# This will raise TypeError: _run_mineru_command() got an unexpected keyword argument 'foo'

MineruParser().parse_document("file.pdf", foo="bar")

```

**Correct usage with documented parameters:**

```python
from raganything.parser import MineruParser

content = MineruParser().parse_document(
    "file.pdf",
    output_dir="/tmp/output",
    method="ocr",           # ocr, txt, or auto

    lang="en",
    device="cuda"
)

```

Valid parameters include: `output_dir`, `method`, `lang`, `backend`, `device`, and `env`.

## Handling Custom Environment Variables

For advanced troubleshooting scenarios, you can pass custom environment variables to the MinerU subprocess via the `env` parameter. This extends the subprocess environment without raising the `TypeError` that unsupported kwargs trigger.

```python
from raganything.parser import MineruParser

custom_env = {
    "MINERU_BACKEND": "vllm",
    "MINERU_DEVICE": "cuda"
}

content = MineruParser().parse_document(
    "image.png",
    method="ocr",
    env=custom_env  # passes through to subprocess

)

```

Any keys other than `env` that are not in the documented parameter list will trigger the validation error in lines 704–708.

## Validating Image Format Support

MinerU natively accepts `png`, `jpeg`, `jpg`, `bmp`, `tiff`, `gif`, and `webp` formats. The `parse_document()` method in [`parser.py`](https://github.com/HKUDS/RAG-Anything/blob/main/parser.py) lines 1090–1094 logs warnings for unsupported formats and attempts conversion.

Ensure your images are in supported formats, or let the helper convert them:

```python
from raganything.parser import MineruParser

# This will work natively

content = MineruParser().parse_document("document.png")

# Unsupported formats trigger conversion warnings

content = MineruParser().parse_document("document.heic")  # logs warning

```

## Using Parser Fallbacks in RAG-Anything

The high-level `RagAnything` API includes installation guards and fallback logic. In [`raganything/raganything.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/raganything.py) line 260, `doc_parser.check_installation()` prevents proceeding with a missing parser.

The [`raganything/processor.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/processor.py) lines 392–398 show automatic fallback to `MineruParser` for image parsing when the chosen parser cannot handle images.

**Explicit fallback strategy:**

```python
from raganything import RagAnything
from raganything.parser import MineruParser, DoclingParser

# Prefer MinerU, but fall back to Docling if unavailable

parser = MineruParser() if MineruParser.check_installation() else DoclingParser()
rag = RagAnything(doc_parser=parser)

# Parse with your resilient configuration

content = rag.doc_parser.parse_document("sample.pdf")
print(content[:2])  # show first 2 content blocks

```

## Running the Built-in Test Suite

The repository includes comprehensive tests that validate installation detection and error handling. Run these to diagnose environment issues:

```bash
pytest tests/testparser_wiring.py

```

Test failures on `check_installation` indicate a broken MinerU installation that requires reinstallation or `PATH` correction.

## Summary

- **Verify installation** with `MineruParser.check_installation()` before parsing documents
- **Use MinerU 2.x** and handle Office documents by pre-converting to PDF or using `DoclingParser`
- **Enable logging** to capture `[MinerU]` prefixed diagnostic messages
- **Avoid unsupported kwargs**; use only documented parameters (`output_dir`, `method`, `lang`, `device`, `env`)
- **Pass custom environment variables** via the `env` parameter for advanced configuration
- **Validate image formats** or convert unsupported formats before parsing
- **Implement fallback parsers** when MinerU is unavailable using `check_installation()` conditionals
- **Run test suite** with `pytest tests/testparser_wiring.py` to validate your environment

## Frequently Asked Questions

### How do I know if MinerU is properly installed for RAG-Anything?

Run `MineruParser.check_installation()` from [`raganything/parser.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/parser.py). It returns `True` if the `mineru --version` command succeeds in a subprocess. If `False`, install with `pip install -U "mineru[core]"` and ensure the binary is on your system `PATH`.

### Why does parsing Office documents fail with MinerU 2.0?

MinerU 2.0 removed bundled LibreOffice conversion. According to the header comment in [`parser.py`](https://github.com/HKUDS/RAG-Anything/blob/main/parser.py) lines 19–22, you must either convert Office files to PDF externally using `soffice --headless --convert-to pdf`, or switch to `DoclingParser` which natively handles `.docx` and `.pptx` formats.

### What causes "unexpected keyword argument" errors when calling parse_document?

The `_run_mineru_command()` method in [`parser.py`](https://github.com/HKUDS/RAG-Anything/blob/main/parser.py) lines 704–708 validates all kwargs. Only documented parameters are accepted: `output_dir`, `method`, `lang`, `backend`, `device`, and `env`. Passing any other key raises `TypeError`. Use the `env` parameter for custom environment variables instead of passing them as top-level kwargs.