opendatalab/MinerU · error · ValueError

Unsupported hybrid effort: {effort}

Error message

Unsupported hybrid effort: {effort}

What it means

A defensive guard in the synchronous hybrid analysis loop (hybrid_analyze.py:1035) reached when effort matches neither the medium nor the high branch of the effort dispatch chain. In principle _validate_parse_effort() should have rejected such values earlier, so hitting this line means validation was bypassed or the dispatch branches got out of sync with the allowed set.

Source

Thrown at mineru/backend/hybrid/hybrid_analyze.py:1035

                                hybrid_pipeline_model=hybrid_pipeline_model,
                            )
                        else:
                            with predictor_execution_guard(predictor):
                                window_model_list = predictor.batch_two_step_extract(
                                    images=images_pil_list,
                                    not_extract_list=not_extract_list,
                                    image_analysis=effective_image_analysis,
                                )
                            window_model_list = _process_ocr_and_formulas(
                                images_pil_list,
                                window_model_list,
                                inline_formula_enable,
                                batch_ratio=batch_ratio,
                                images_layout_res=images_layout_res,
                                hybrid_pipeline_model=hybrid_pipeline_model,
                            )
                    else:
                        raise ValueError(f"Unsupported hybrid effort: {effort}")

                    _apply_layout_title_split(
                        window_model_list,
                        images_layout_res,
                        page_sizes,
                    )
                    model_list.extend(window_model_list)
                    if progress_bar is None:
                        progress_bar = tqdm(total=page_count, desc="Processing pages")
                    else:
                        exclude_progress_bar_idle_time(
                            progress_bar,
                            last_append_end_time,
                            now=time.time(),
                        )
                    append_page_model_list_to_middle_json(
                        middle_json,
                        window_model_list,

View on GitHub (pinned to 4fe4bde114)

Solutions

1. Use the public entry point that runs _validate_parse_effort() and pass effort="medium" or "high".
2. Ensure only one mineru version is importable (pip show mineru; check for stale copies in site-packages or cwd).
3. If you maintain a fork adding a new effort level, add its dispatch branch alongside the raise.

Example fix

# before
model_list = hybrid_page_loop(windows, effort="ultra")  # internal call, no validation

# after
from mineru.backend.hybrid.hybrid_analyze import _validate_parse_effort
effort = _validate_parse_effort("high")
model_list = hybrid_page_loop(windows, effort=effort)

from mineru.backend.hybrid.hybrid_analyze import _validate_parse_effort

# call the public API; if you must call internals, validate first:
effort = _validate_parse_effort(request.args.get("effort", "medium"))

ALLOWED = {"medium", "high"}

def is_valid_effort(v: object) -> bool:
    return isinstance(v, str) and v in ALLOWED

try:
    model_list = hybrid_page_loop(windows, effort=effort)
except ValueError as e:
    if "Unsupported hybrid effort" in str(e):
        raise ConfigError("hybrid effort out of range; use medium/high") from e
    raise

When it happens

Trigger: effort passing early validation but not matching any if/elif branch in the page-window loop; typically only possible with inconsistent code paths, monkeypatched validators, or an internal call that skips validation.

Common situations: Calling the internal analysis loop directly instead of the public API; patched/older copies of the module mixed at runtime; a new effort value added to HYBRID_ANALYZE_EFFORTS without a matching branch here.

Related errors

• effort must be "medium" or "high"
• Invalid effort. Allowed values: {allowed_values}
• Invalid effort. Allowed values: {allowed_values}
• `{backend}` requires local pipeline dependencies (`mineru[pi

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