opendatalab/MinerU · error · ValueError

Unknown backend type: {backend}

Error message

Unknown backend type: {backend}

What it means

ValueError raised by build_parse_dir in mineru/cli/output_paths.py: the backend string must start with 'pipeline', 'vlm', or 'hybrid' (prefix matching, so 'vlm-engine' etc. pass), otherwise the output directory layout is undefined and the function refuses. The backend value typically comes from the CLI --backend flag or API request options, so this is usually a user-supplied string validation failure.

Source

Thrown at mineru/cli/output_paths.py:26

def build_parse_dir(
    output_dir: str | Path,
    pdf_name: str,
    backend: str,
    parse_method: str,
    *,
    is_office: bool = False,
) -> Path:
    output_root = Path(output_dir)
    if is_office:
        return output_root / pdf_name / OFFICE_PARSE_DIR_NAME
    if backend.startswith("pipeline"):
        return output_root / pdf_name / parse_method
    if backend.startswith("vlm"):
        return output_root / pdf_name / VLM_PARSE_DIR_NAME
    if backend.startswith("hybrid"):
        return output_root / pdf_name / f"hybrid_{parse_method}"
    raise ValueError(f"Unknown backend type: {backend}")


def resolve_parse_dir(
    output_dir: str | Path,
    pdf_name: str,
    backend: str,
    parse_method: str,
    *,
    is_office: bool = False,
    allow_office_fallback: bool = False,
) -> Path:
    parse_dir = build_parse_dir(
        output_dir,
        pdf_name,
        backend,
        parse_method,
        is_office=is_office,
    )

View on GitHub (pinned to 4fe4bde114)

Solutions

1. Use one of the supported backends: pipeline (optionally with a '-...' subtag), vlm, or hybrid.
2. Check for typos, casing, and stray whitespace/quotes in the --backend value.
3. If you need a custom backend name, map it to a supported prefix before calling output-path helpers (e.g. 'my_vlm' -> 'vlm' for layout purposes).
4. Upgrade mineru if you expected a newer backend name (e.g. hybrid) to exist.

Example fix

# before
subprocess.run(['mineru', '-p', 'file.pdf', '-b', 'auto'])  # ValueError: Unknown backend type: auto

# after
subprocess.run(['mineru', '-p', 'file.pdf', '-b', 'hybrid'])  # or 'pipeline' / 'vlm'

ALLOWED_BACKEND_PREFIXES = ('pipeline', 'vlm', 'hybrid')

def normalize_backend(backend: str) -> str:
    b = backend.strip().lower()
    if not b.startswith(ALLOWED_BACKEND_PREFIXES):
        raise ValueError(f"backend must start with one of {ALLOWED_BACKEND_PREFIXES}, got {backend!r}")
    return b

def is_supported_backend(backend: str) -> bool:
    return isinstance(backend, str) and backend.strip().lower().startswith(('pipeline', 'vlm', 'hybrid'))

When it happens

Trigger: Running the CLI or API with --backend txt, --backend auto, or a typo like 'pipiline'/'vlmm'; programmatic callers passing backend='none'; values with wrong casing ('Pipeline') since startswith is case-sensitive.

Common situations: Copy-pasting commands from docs of a different mineru version that had other backend names; shell-quoting mistakes leaving a stray character in the value; wrapper scripts mapping their own backend names without translating them.

Related errors

• Unknown process_mode: {process_mode}
• Invalid backend. Allowed values: {allowed_values}
• Invalid effort. Allowed values: {allowed_values}
• max_concurrent_requests must be a positive integer
• Unsupported office suffix: {file_suffix}

AI-assisted analysis of opendatalab/MinerU@4fe4bde114 (2026-08-14). Data as JSON: /api/errors/3e7d8bf9c8dd2de9. Report an issue: GitHub.