docling-project/docling · error · ValueError

Unknown RapidOCR backend {backend!r} in {value!r}. Supported

Error message

Unknown RapidOCR backend {backend!r} in {value!r}. Supported: {list(_RAPIDOCR_BACKENDS)}.

What it means

After the '<backend>:<lang>' shape check, the parser verifies the backend part against _RAPIDOCR_BACKENDS (onnxruntime, openvino, paddle, torch — the inference engines rapidocr supports). An unknown backend name raises ValueError listing the supported set, so the failure happens at configuration time rather than deep inside rapidocr.

Source

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

    # 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

    engine_types = {
        "onnxruntime": EngineType.ONNXRUNTIME,
        "openvino": EngineType.OPENVINO,
        "paddle": EngineType.PADDLE,

View on GitHub (pinned to 61d76f1ff3)

Solutions

Use only backends from the supported list printed in the error, e.g. 'onnxruntime:th'.
Install the engine you want (e.g. onnxruntime or openvino) and keep the spec string aligned with that engine's name.
Upgrade docling if you expected a newly added backend (like torch) that your version does not know.

Example fix

# before
spec = "onnx:th"  # backend not in _RAPIDOCR_BACKENDS -> ValueError

# after
spec = "onnxruntime:th"

Defensive patterns

Strategy: validation

Validate before calling

RAPIDOCR_BACKENDS = {"onnxruntime", "openvino", "paddle", "torch"}

def valid_backend(spec: str) -> bool:
    return spec.partition(":")[0] in RAPIDOCR_BACKENDS

Type guard

def is_known_rapidocr_backend(backend: str) -> bool:
    return backend in {"onnxruntime", "openvino", "paddle", "torch"}

Prevention

Copy backend names from the error message's supported list, never from memory or other tools.
Pin the docling version whose backend list you coded against; re-check on upgrades.
Use config enums/literals for backend names to make typos impossible.

When it happens

Trigger: Passing a spec like 'onnx:th', 'cuda:en', or 'paddlelite:ch' — any backend string not in _RAPIDOCR_BACKENDS — to the RapidOCR model prefetch configuration.

Common situations: Using rapidocr's own backend names or GPU labels from other tools; older docling versions with a smaller backend set; guessing engine names instead of checking the supported list.

Related errors

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