docling-project/docling · error · ValueError

Unknown RapidOCR backend

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.

Solutions

1. Use only backends from the supported list printed in the error, e.g. 'onnxruntime:th'.
2. Install the engine you want (e.g. onnxruntime or openvino) and keep the spec string aligned with that engine's name.
3. 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"

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

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

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

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

• Invalid RapidOCR model spec
• Invalid RapidOCR model spec
• RapidOCR backend does not support language . Supported: .
• Unknown RapidOCR backend
• Cannot specify both ocr_preset and ocr_custom_config.

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

Appendix: 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)