{"record":{"id":"faa5acbb9c44b09b","repo":"opendatalab/MinerU","slug":"backend-backend-requires-server-url","errorCode":null,"errorMessage":"backend={backend} requires server_url","messagePattern":"backend=(.+?) requires server_url","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"demo/demo.py","lineNumber":114,"sourceCode":"    input_path: str | Path,\n    output_dir: str | Path,\n    *,\n    api_url: str | None = None,\n    backend: str = \"hybrid-engine\",\n    parse_method: str = \"auto\",\n    language: str = \"ch\",\n    formula_enable: bool = True,\n    table_enable: bool = True,\n    image_analysis: bool = True,\n    effort: str = \"medium\",\n    server_url: str | None = None,\n    start_page_id: int = 0,\n    end_page_id: int | None = None,\n) -> None:\n    api_url = api_url or None\n    server_url = server_url or None\n    if backend.endswith(\"http-client\") and not server_url:\n        raise ValueError(f\"backend={backend} requires server_url\")\n\n    input_files = collect_input_files(input_path)\n    output_path = Path(output_dir).expanduser().resolve()\n    output_path.mkdir(parents=True, exist_ok=True)\n\n    form_data = build_form_data(\n        language=language,\n        backend=backend,\n        parse_method=parse_method,\n        formula_enable=formula_enable,\n        table_enable=table_enable,\n        image_analysis=image_analysis,\n        effort=effort,\n        server_url=server_url,\n        start_page_id=start_page_id,\n        end_page_id=end_page_id,\n    )\n    upload_assets = [","sourceCodeStart":96,"sourceCodeEnd":132,"githubUrl":"https://github.com/opendatalab/MinerU/blob/4fe4bde114a23ee5dd637eae99b767f4669bf58c/demo/demo.py#L96-L132","documentation":"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.","triggerScenarios":"Calling with backend=\"vlm-http-client\" (or any *-http-client backend) while omitting server_url or passing \"\" / whitespace-free empty value.","commonSituations":"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.","solutions":["Pass a valid server_url, e.g. server_url=\"http://127.0.0.1:8000\", pointing at a running MinerU API service.","Start the service first (mineru-api or your deployment) and confirm it responds (curl the health endpoint).","If you wanted local execution, use a non-http-client backend (e.g. pipeline or the local vlm backend) instead."],"exampleFix":"# before\nrun(input_path=\"a.pdf\", backend=\"vlm-http-client\")\n\n# after\nrun(input_path=\"a.pdf\", backend=\"vlm-http-client\", server_url=\"http://127.0.0.1:8000\")","handlingStrategy":"validation","validationCode":"def validate_http_client_config(backend: str, server_url: str | None) -> None:\n    if backend.endswith(\"http-client\") and not server_url:\n        raise ValueError(f\"backend={backend} requires server_url\")\n\nvalidate_http_client_config(backend, server_url)","typeGuard":null,"tryCatchPattern":"try:\n    run(input_path=p, backend=\"vlm-http-client\", server_url=server_url)\nexcept ValueError as e:\n    if \"requires server_url\" in str(e):\n        server_url = os.environ.get(\"MINERU_SERVER_URL\") or input(\"server URL: \")\n        run(input_path=p, backend=\"vlm-http-client\", server_url=server_url)\n    else:\n        raise","preventionTips":["Pair http-client backends with an explicit server_url in config; fail startup if missing.","Health-check the server (GET /health) before dispatching documents.","Keep local vs remote backend selection in one config branch so they stay consistent."],"tags":["configuration","http-client","backend","server-url"],"backgroundTag":null,"analyzedSha":"4fe4bde114a23ee5dd637eae99b767f4669bf58c","analyzedAt":"2026-08-14T21:29:18.456Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}