opendatalab/MinerU · error · ValueError

backend={backend} requires server_url

Error message

backend={backend} requires server_url

What it means

Raised in the demo entry point when backend is an http-client variant (backend.endswith("http-client")) but server_url is empty/None. HTTP-client backends only package the request and POST it to a remote MinerU service, so a service URL is mandatory. Note that empty strings are normalized to None via `server_url = server_url or None` before the check.

Source

Thrown at demo/demo.py:114

    input_path: str | Path,
    output_dir: str | Path,
    *,
    api_url: str | None = None,
    backend: str = "hybrid-engine",
    parse_method: str = "auto",
    language: str = "ch",
    formula_enable: bool = True,
    table_enable: bool = True,
    image_analysis: bool = True,
    effort: str = "medium",
    server_url: str | None = None,
    start_page_id: int = 0,
    end_page_id: int | None = None,
) -> None:
    api_url = api_url or None
    server_url = server_url or None
    if backend.endswith("http-client") and not server_url:
        raise ValueError(f"backend={backend} requires server_url")

    input_files = collect_input_files(input_path)
    output_path = Path(output_dir).expanduser().resolve()
    output_path.mkdir(parents=True, exist_ok=True)

    form_data = build_form_data(
        language=language,
        backend=backend,
        parse_method=parse_method,
        formula_enable=formula_enable,
        table_enable=table_enable,
        image_analysis=image_analysis,
        effort=effort,
        server_url=server_url,
        start_page_id=start_page_id,
        end_page_id=end_page_id,
    )
    upload_assets = [

View on GitHub (pinned to 4fe4bde114)

Solutions

1. Pass a valid server_url, e.g. server_url="http://127.0.0.1:8000", pointing at a running MinerU API service.
2. Start the service first (mineru-api or your deployment) and confirm it responds (curl the health endpoint).
3. If you wanted local execution, use a non-http-client backend (e.g. pipeline or the local vlm backend) instead.

Example fix

# before
run(input_path="a.pdf", backend="vlm-http-client")

# after
run(input_path="a.pdf", backend="vlm-http-client", server_url="http://127.0.0.1:8000")

def validate_http_client_config(backend: str, server_url: str | None) -> None:
    if backend.endswith("http-client") and not server_url:
        raise ValueError(f"backend={backend} requires server_url")

validate_http_client_config(backend, server_url)

try:
    run(input_path=p, backend="vlm-http-client", server_url=server_url)
except ValueError as e:
    if "requires server_url" in str(e):
        server_url = os.environ.get("MINERU_SERVER_URL") or input("server URL: ")
        run(input_path=p, backend="vlm-http-client", server_url=server_url)
    else:
        raise

When it happens

Trigger: Calling with backend="vlm-http-client" (or any *-http-client backend) while omitting server_url or passing "" / whitespace-free empty value.

Common situations: Copy-pasting a local-backend invocation and only changing backend; forgetting that the demo cannot run the server itself; env var for the URL not exported so it arrives as None.

Related errors

• Unsupported lmdeploy backend: {lm_backend}
• Invalid backend. Allowed values: {allowed_values}
• effort must be "medium" or "high"
• Unsupported lmdeploy device type: {device_type}
• Please install transformers to use the transformers backend.

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