{"record":{"id":"f1c73112294e6b4d","repo":"docling-project/docling","slug":"invalid-rapidocr-model-spec-value-r-err","errorCode":null,"errorMessage":"Invalid RapidOCR model spec {value!r}: {err}","messagePattern":"Invalid RapidOCR model spec (.+?): (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/models/stages/ocr/rapid_ocr_model.py","lineNumber":119,"sourceCode":"\n    The pair is routed through _resolve_rapidocr so the prefetcher can never accept a\n    combination the runtime would reject, but only the user's own values are kept.\n    \"\"\"\n    backend, separator, lang = value.partition(\":\")\n    if not separator or not backend or not lang or \":\" in lang:\n        raise ValueError(\n            f\"Invalid RapidOCR model spec {value!r}. \"\n            \"Expected '<backend>:<lang>', e.g. 'onnxruntime:th'.\"\n        )\n    if backend not in _RAPIDOCR_BACKENDS:\n        raise ValueError(\n            f\"Unknown RapidOCR backend {backend!r} in {value!r}. \"\n            f\"Supported: {list(_RAPIDOCR_BACKENDS)}.\"\n        )\n    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]","sourceCodeStart":101,"sourceCodeEnd":137,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/stages/ocr/rapid_ocr_model.py#L101-L137","documentation":"The final validation step routes the (backend, lang) pair through _resolve_rapidocr, which checks that the language is actually resolvable for that backend. If resolution raises ValueError, it is re-raised wrapped as \"Invalid RapidOCR model spec {value!r}: {err}\" so the original cause (usually an unsupported language) is preserved. This guarantees the prefetcher never accepts a combination the runtime itself would reject.","triggerScenarios":"A well-formed spec like 'onnxruntime:zz' where the language code is not supported by rapidocr for that backend — _resolve_rapidocr raises and the wrapper converts it into this prefixed ValueError.","commonSituations":"Requesting languages rapidocr does not ship models for; mixing language codes from other OCR engines; backend-specific language availability differences (a lang valid on onnxruntime but not on paddle).","solutions":["Use a language code supported by rapidocr for the chosen backend (see the resolution table in rapid_ocr_model.py / rapidocr docs).","If the language is unsupported, pick a different OCR engine that covers it (Tesseract, EasyOCR).","Read the inner {err} message — it names the exact unsupported value to correct."],"exampleFix":"# before\nmodels = [\"onnxruntime:zz\"]  # unsupported language -> wrapped ValueError\n\n# after\nmodels = [\"onnxruntime:th\"]  # supported language","handlingStrategy":"validation","validationCode":"from docling.models.stages.ocr.rapid_ocr_model import _resolve_rapidocr\n\ndef lang_supported(lang: str, backend: str) -> bool:\n    try:\n        _resolve_rapidocr(lang, backend)\n        return True\n    except ValueError:\n        return False","typeGuard":null,"tryCatchPattern":"try:\n    specs = [_parse_rapidocr_model_spec(s) for s in raw_specs]\nexcept ValueError as err:\n    # err.__cause__ carries the inner unsupported-language reason\n    logger.error(\"Unsupported RapidOCR (backend, lang): %s\", err)\n    raw_specs = [s for s in raw_specs if s != offending_spec]","preventionTips":["Reuse docling's own _resolve_rapidocr as the validator for (lang, backend) pairs.","Keep the language list limited to codes rapidocr ships models for.","On ValueError, read the inner {err} text — it identifies exactly which component is unsupported."],"tags":["rapidocr","ocr","language","validation"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}