docling-project/docling · error · ValueError

Invalid RapidOCR model spec {value!r}. Expected '<backend>:<

Error message

Invalid RapidOCR model spec {value!r}. Expected '<backend>:<lang>', e.g. 'onnxruntime:th'.

What it means

RapidOCR model prefetching accepts specs of the exact form '<backend>:<lang>' (e.g. 'onnxruntime:th'). _parse_rapidocr_model_spec splits on ':' and raises ValueError for the whole spec string when it is malformed: missing separator, empty backend, empty language, or a second ':' in the language part. The error quotes the offending value and shows the expected shape.

Source

Thrown at docling/models/stages/ocr/rapid_ocr_model.py:107

    # Language exactly as the user wrote it
    user_lang: str | None = None

    # Language code the rapidocr registry expects, after normalization and aliasing.
    rapidocr_lang_token: str | None = None

    # PP-OCR backbone that the (backend, language) pair resolves to.
    ppocr_version: "OCRVersion | None" = None


def _parse_rapidocr_model_spec(value: str) -> _RapidOcrModelSpec:
    """Parse a `<backend>:<lang>` prefetch spec into its requested form.

    The pair is routed through _resolve_rapidocr so the prefetcher can never accept a
    combination the runtime would reject, but only the user's own values are kept.
    """
    backend, separator, lang = value.partition(":")
    if not separator or not backend or not lang or ":" in lang:
        raise ValueError(
            f"Invalid RapidOCR model spec {value!r}. "
            "Expected '<backend>:<lang>', e.g. 'onnxruntime:th'."
        )
    if backend not in _RAPIDOCR_BACKENDS:
        raise ValueError(
            f"Unknown RapidOCR backend {backend!r} in {value!r}. "
            f"Supported: {list(_RAPIDOCR_BACKENDS)}."
        )
    try:
        _resolve_rapidocr(lang, backend)
    except ValueError as err:
        raise ValueError(f"Invalid RapidOCR model spec {value!r}: {err}") from err
    return _RapidOcrModelSpec(backend=backend, user_lang=lang)


def _backend_to_engine_type(backend: str) -> "EngineType":
    """Map a docling backend name onto the rapidocr EngineType it stands for."""
    from rapidocr.utils.typings import EngineType

View on GitHub (pinned to 61d76f1ff3)

Solutions

  1. Format every spec as exactly '<backend>:<lang>', e.g. 'onnxruntime:th' or 'openvino:en'.
  2. Validate specs at config-load time with the same partition(':') check before passing them to docling.
  3. Use one of the known backends (see _RAPIDOCR_BACKENDS: onnxruntime, openvino, paddle, torch) and a supported language code.

Example fix

# before
models = ["onnxruntime-th", "onnxruntime:th:ch"]  # wrong separators -> ValueError

# after
models = ["onnxruntime:th", "openvino:en"]
Defensive patterns

Strategy: validation

Validate before calling

import re

SPEC_RE = re.compile(r"^(onnxruntime|openvino|paddle|torch):[^:]+$")

def valid_rapidocr_spec(spec: str) -> bool:
    return bool(SPEC_RE.match(spec))

specs = [s for s in configs["models"] if valid_rapidocr_spec(s)]

Type guard

def is_valid_rapidocr_spec(value: str) -> bool:
    backend, sep, lang = value.partition(":")
    return bool(sep and backend and lang and ":" not in lang)

Try / catch

try:
    specs = [_parse_rapidocr_model_spec(s) for s in raw_specs]
except ValueError as err:
    raise ConfigError(f"Bad RapidOCR model config: {err}") from err

Prevention

When it happens

Trigger: Configuring RapidOCR prefetch model specs with values like 'onnxruntime' (no colon), ':th', 'onnxruntime:', or 'onnxruntime:th:extra' — the partition/validation in the parser fails.

Common situations: Hand-written YAML/JSON pipeline configs with typos; env-var-driven specs concatenated incorrectly; whitespace-only segments after trimming.

Related errors

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/fd63a1c7859dadf1. Report an issue: GitHub.