HKUDS/DeepTutor · error · MinerUError

Local MinerU parsing failed. Ensure MinerU is installed (`pi

Error message

Local MinerU parsing failed. Ensure MinerU is installed (`pip install mineru`) or switch to cloud mode in Settings → MinerU.

What it means

The MinerU CLI subprocess ran but returned a non-zero exit status, so the backend raises MinerUError advising installation or cloud mode. It masks the CLI's own stderr detail.

Source

Thrown at deeptutor/services/parsing/engines/mineru/backend.py:155

        cli_command = probe["path"]

    # A lazy first-parse model download must honor the configured source and
    # custom address, not just the explicit Download button.
    download_env = model_env_overrides(config.model_download_source, config.model_download_endpoint)
    # Only the local CLI renders pages in this process tree; cloud mode never
    # does, so the Windows render-thread guard belongs on this branch alone.
    subprocess_env = {**download_env, **render_env_overrides()}

    logger.info("Parsing %s via local MinerU CLI (%s)", pdf_path.name, cli_command or "PATH")
    ok = parse_pdf_with_mineru(
        str(pdf_path),
        str(output_base),
        on_output=on_output,
        cli_command=cli_command,
        extra_env=subprocess_env,
    )
    if not ok:
        raise MinerUError(
            "Local MinerU parsing failed. Ensure MinerU is installed "
            "(`pip install mineru`) or switch to cloud mode in Settings → MinerU."
        )
    working_dir = output_base / pdf_path.stem
    if not working_dir.is_dir():
        # Defensive: the CLI names its output dir after the PDF stem, but fall
        # back to the newest sub-directory if that assumption ever breaks.
        subdirs = sorted(
            (d for d in output_base.iterdir() if d.is_dir()),
            key=lambda d: d.stat().st_mtime,
            reverse=True,
        )
        if not subdirs:
            raise MinerUError("MinerU produced no output directory.")
        working_dir = subdirs[0]
    return working_dir

View on GitHub (pinned to 3e82f13042)

Solutions

1. Run the same mineru command manually in the app's env to see the real error.
2. pip install mineru (or fix the broken install) in that environment.
3. If models fail to download, configure a reachable model source (see model_env_overrides).
4. Switch to cloud mode in Settings → MinerU as a workaround.

Example fix

# before
mode = "local"

# after (workaround when local install can't be fixed)
mode = "cloud"  # Settings → MinerU

import shutil
local_ready = shutil.which("mineru") is not None or bool((cfg.local_cli_path or "").strip())

try:
    parse_pdf_to_workdir(pdf, wd, cfg)
except MinerUError as e:
    if "Local MinerU parsing failed" in str(e):
        run_cloud(pdf, wd, cfg)  # fallback mode

When it happens

Trigger: _run returning ok=False — mineru CLI crashed, missing model weights, out-of-memory, unsupported PDF, or mineru not importable in the subprocess environment.

Common situations: mineru not installed in the app's environment, first-run model download failing, CUDA/dependency issues, or a corrupt/oversized PDF.

Related errors

• MinerU failed to parse the document: {err}
• Configured MinerU CLI path is not an executable file: {probe
• MinerU produced no output directory.
• The model provider interrupted this response. Please retry.
• Unable to reach the model provider. Please retry.

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