{"record":{"id":"d08796158f7e2477","repo":"HKUDS/DeepTutor","slug":"local-mineru-parsing-failed-ensure-mineru-is-inst","errorCode":null,"errorMessage":"Local MinerU parsing failed. Ensure MinerU is installed (`pip install mineru`) or switch to cloud mode in Settings → MinerU.","messagePattern":"Local MinerU parsing failed\\. Ensure MinerU is installed \\(`pip install mineru`\\) or switch to cloud mode in Settings → MinerU\\.","errorType":"exception","errorClass":"MinerUError","httpStatus":null,"severity":"error","filePath":"deeptutor/services/parsing/engines/mineru/backend.py","lineNumber":155,"sourceCode":"        cli_command = probe[\"path\"]\n\n    # A lazy first-parse model download must honor the configured source and\n    # custom address, not just the explicit Download button.\n    download_env = model_env_overrides(config.model_download_source, config.model_download_endpoint)\n    # Only the local CLI renders pages in this process tree; cloud mode never\n    # does, so the Windows render-thread guard belongs on this branch alone.\n    subprocess_env = {**download_env, **render_env_overrides()}\n\n    logger.info(\"Parsing %s via local MinerU CLI (%s)\", pdf_path.name, cli_command or \"PATH\")\n    ok = parse_pdf_with_mineru(\n        str(pdf_path),\n        str(output_base),\n        on_output=on_output,\n        cli_command=cli_command,\n        extra_env=subprocess_env,\n    )\n    if not ok:\n        raise MinerUError(\n            \"Local MinerU parsing failed. Ensure MinerU is installed \"\n            \"(`pip install mineru`) or switch to cloud mode in Settings → MinerU.\"\n        )\n    working_dir = output_base / pdf_path.stem\n    if not working_dir.is_dir():\n        # Defensive: the CLI names its output dir after the PDF stem, but fall\n        # back to the newest sub-directory if that assumption ever breaks.\n        subdirs = sorted(\n            (d for d in output_base.iterdir() if d.is_dir()),\n            key=lambda d: d.stat().st_mtime,\n            reverse=True,\n        )\n        if not subdirs:\n            raise MinerUError(\"MinerU produced no output directory.\")\n        working_dir = subdirs[0]\n    return working_dir\n\n","sourceCodeStart":137,"sourceCodeEnd":173,"githubUrl":"https://github.com/HKUDS/DeepTutor/blob/3e82f130422a813cdd73c10b21a44e9325f5821a/deeptutor/services/parsing/engines/mineru/backend.py#L137-L173","documentation":"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.","triggerScenarios":"_run returning ok=False — mineru CLI crashed, missing model weights, out-of-memory, unsupported PDF, or mineru not importable in the subprocess environment.","commonSituations":"mineru not installed in the app's environment, first-run model download failing, CUDA/dependency issues, or a corrupt/oversized PDF.","solutions":["Run the same mineru command manually in the app's env to see the real error.","pip install mineru (or fix the broken install) in that environment.","If models fail to download, configure a reachable model source (see model_env_overrides).","Switch to cloud mode in Settings → MinerU as a workaround."],"exampleFix":"# before\nmode = \"local\"\n\n# after (workaround when local install can't be fixed)\nmode = \"cloud\"  # Settings → MinerU","handlingStrategy":"try-catch","validationCode":"import shutil\nlocal_ready = shutil.which(\"mineru\") is not None or bool((cfg.local_cli_path or \"\").strip())","typeGuard":null,"tryCatchPattern":"try:\n    parse_pdf_to_workdir(pdf, wd, cfg)\nexcept MinerUError as e:\n    if \"Local MinerU parsing failed\" in str(e):\n        run_cloud(pdf, wd, cfg)  # fallback mode","preventionTips":["Verify `mineru --version` works in the app's environment before selecting local mode.","Pre-download model weights once after install.","Have cloud credentials configured as a fallback."],"tags":["mineru","pdf","subprocess","ocr"],"backgroundTag":"subprocess-exit-nonzero","analyzedSha":"3e82f130422a813cdd73c10b21a44e9325f5821a","analyzedAt":"2026-08-27T06:57:25.364Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}