opendatalab/MinerU · error · HTTPException

Invalid effort. Allowed values: {allowed_values}

Error message

Invalid effort. Allowed values: {allowed_values}

What it means

HTTP 400 raised by validate_parse_effort(): hybrid backends accept an effort parameter restricted to HYBRID_EFFORT_CHOICES = ('medium','high'). Anything else — 'low', 'max', 'MEDIUM', 'auto' — is rejected before parsing starts.

Source

Thrown at mineru/cli/api_request.py:81

            ),
        )
    return parse_method


def validate_parse_backend(backend: str) -> str:
    """校验公开 API 允许的解析后端，避免旧入口名进入下游执行链路。"""
    try:
        return validate_public_backend(backend)
    except ValueError as exc:
        raise HTTPException(status_code=400, detail=str(exc)) from exc


def validate_parse_effort(effort: str) -> str:
    """校验公开 API 允许的 hybrid effort，避免非法值进入解析链路。"""
    try:
        return validate_public_effort(effort)
    except ValueError as exc:
        raise HTTPException(status_code=400, detail=str(exc)) from exc


def validate_parse_lang_list(lang_list: list[str]) -> list[str]:
    """校验公开 API 允许的 OCR 语言列表，避免旧语言入口进入解析链路。"""
    try:
        return validate_public_ocr_lang_list(lang_list)
    except ValueError as exc:
        raise HTTPException(status_code=400, detail=str(exc)) from exc


async def parse_request_form(
    request: Request,
    files: Annotated[
        list[UploadFile],
        File(
            description="Upload PDF, image, DOCX, PPTX, or XLSX files for parsing",
            json_schema_extra=SWAGGER_UI_FILE_ARRAY_SCHEMA_EXTRA,
        ),

View on GitHub (pinned to 4fe4bde114)

Solutions

  1. Use 'medium' or 'high' exactly (lowercase)
  2. Or omit the effort parameter entirely to get the default 'medium'
  3. Check HYBRID_EFFORT_CHOICES in backend_options.py if running an unreleased fork — choices may differ
  4. For lighter runs, prefer effort=medium over invented 'low' values

Example fix

# before
data = {'backend': 'hybrid-engine', 'parse_effort': 'low'}

# after
data = {'backend': 'hybrid-engine', 'parse_effort': 'medium'}
Defensive patterns

Strategy: validation

Validate before calling

from mineru.cli.backend_options import HYBRID_EFFORT_CHOICES  # ('medium','high')

effort = (effort or "medium").strip().lower()
assert effort in HYBRID_EFFORT_CHOICES, f"effort must be one of {HYBRID_EFFORT_CHOICES}"

Type guard

def is_valid_effort(v: str | None) -> bool:
    return v is None or (isinstance(v, str) and v.strip().lower() in {"medium", "high"})

Try / catch

try:
    resp = requests.post(url, files=files, data={"backend": b, "parse_effort": effort}, timeout=60)
    resp.raise_for_status()
except requests.HTTPError as e:
    if e.response.status_code == 400 and "effort" in e.response.text:
        data.pop("parse_effort")  # omit and use server default
        resp = requests.post(url, files=files, data=data, timeout=60)
    else:
        raise

Prevention

When it happens

Trigger: POSTing backend=hybrid-engine (or hybrid-http-client) with parse_effort='low' or 'fast'; omitting effort is fine (medium is the default) but an explicit invalid string fails.

Common situations: Users assuming an auto/low tier exists because other LLM tools expose it; case-sensitive values copied from docs with capitalized words; configs from versions that once accepted more tiers.

Related errors

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