{"record":{"id":"b89fc05a85db16ac","repo":"docling-project/docling","slug":"unknown-rapidocr-backend-backend-r-supported","errorCode":null,"errorMessage":"Unknown RapidOCR backend {backend!r}. Supported: {list(_RAPIDOCR_BACKENDS)}.","messagePattern":"Unknown RapidOCR backend (.+?)\\. Supported: (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/models/stages/ocr/rapid_ocr_model.py","lineNumber":134,"sourceCode":"    try:\n        _resolve_rapidocr(lang, backend)\n    except ValueError as err:\n        raise ValueError(f\"Invalid RapidOCR model spec {value!r}: {err}\") from err\n    return _RapidOcrModelSpec(backend=backend, user_lang=lang)\n\n\ndef _backend_to_engine_type(backend: str) -> \"EngineType\":\n    \"\"\"Map a docling backend name onto the rapidocr EngineType it stands for.\"\"\"\n    from rapidocr.utils.typings import EngineType\n\n    engine_types = {\n        \"onnxruntime\": EngineType.ONNXRUNTIME,\n        \"openvino\": EngineType.OPENVINO,\n        \"paddle\": EngineType.PADDLE,\n        \"torch\": EngineType.TORCH,\n    }\n    if backend not in engine_types:\n        raise ValueError(\n            f\"Unknown RapidOCR backend {backend!r}. Supported: {list(_RAPIDOCR_BACKENDS)}.\"\n        )\n    return engine_types[backend]\n\n\ndef _resolve_rapidocr(lang: str, backend: str) -> _RapidOcrModelSpec:\n    \"\"\"Map one requested language + backend onto a fully populated _RapidOcrModelSpec.\n\n    - Prefer PP-OCRv6 (whose recognizer is multilingual and covers ~52 codes)\n    - Otherwise fall back to PP-OCRv4 for the torch backend or PP-OCRv5 for the others.\n    - Raises when the language cannot be served by the resolved backbone.\n\n    Callers pass a single language; reducing a multi-language request is up to them.\n    \"\"\"\n    from rapidocr.utils.model_resolver import COMMON_LANG_ALIASES, PP_OCRV6_LANGS\n    from rapidocr.utils.typings import OCRVersion\n\n    code = lang.strip().lower()","sourceCodeStart":116,"sourceCodeEnd":152,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/stages/ocr/rapid_ocr_model.py#L116-L152","documentation":"Docling maps its own RapidOCR backend names onto rapidocr's EngineType via a fixed dict ('onnxruntime', 'openvino', 'paddle', 'torch'). When RapidOcrOptions.backend is not one of those four keys, _backend_to_engine_type raises this ValueError before any OCR work starts. The message lists the valid set taken from _RAPIDOCR_BACKENDS.","triggerScenarios":"Constructing or running a pipeline with RapidOcrOptions(backend=...) set to a typo or unsupported name, e.g. 'onnx', 'cuda', 'pytorch', 'CPU', or a case variant like 'Torch'. Also setting backend from env vars or config files without validating the value.","commonSituations":"Copy-pasting backend names from rapidocr docs that differ from Docling's naming (e.g. rapidocr uses 'onnxruntime' but users type 'ort'); passing accelerator device names instead of backend names; case mismatches.","solutions":["Set backend to one of the exact supported names: 'onnxruntime', 'openvino', 'paddle', or 'torch' (e.g. RapidOcrOptions(backend='onnxruntime')).","Check for typos, leading/trailing whitespace, and case in the backend string coming from config files or environment variables.","If you wanted a GPU/device setting, use AcceleratorOptions (accelerator_options.device), not RapidOcrOptions.backend."],"exampleFix":"# before\nocr_options = RapidOcrOptions(backend=\"ort\")\n\n# after\nocr_options = RapidOcrOptions(backend=\"onnxruntime\")","handlingStrategy":"validation","validationCode":"from docling.models.stages.ocr.rapid_ocr_model import _RAPIDOCR_BACKENDS\n\nbackend = \"onnxruntime\"\nassert backend in _RAPIDOCR_BACKENDS, f\"backend must be one of {sorted(_RAPIDOCR_BACKENDS)}\"","typeGuard":"def is_valid_rapidocr_backend(backend: str) -> bool:\n    from docling.models.stages.ocr.rapid_ocr_model import _RAPIDOCR_BACKENDS\n    return backend in _RAPIDOCR_BACKENDS","tryCatchPattern":"try:\n    ocr = RapidOcrModel(options=RapidOcrOptions(backend=backend))\nexcept ValueError as e:\n    if \"Unknown RapidOCR backend\" in str(e):\n        raise ConfigError(f\"bad backend {backend!r}: {e}\") from e\n    raise","preventionTips":["Keep the allowed backend list in one constant shared by config loading and model construction.","Fail fast at config-load time by validating backend before building the pipeline.","Add unit tests asserting the accepted backend names against _RAPIDOCR_BACKENDS."],"tags":["ocr","rapidocr","configuration","validation"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}