docling-project/docling · error · ValueError

Unknown RapidOCR backend {backend!r}. Supported: {list(_RAPI

Error message

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

What it means

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.

Source

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

    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,
        "torch": EngineType.TORCH,
    }
    if backend not in engine_types:
        raise ValueError(
            f"Unknown RapidOCR backend {backend!r}. Supported: {list(_RAPIDOCR_BACKENDS)}."
        )
    return engine_types[backend]


def _resolve_rapidocr(lang: str, backend: str) -> _RapidOcrModelSpec:
    """Map one requested language + backend onto a fully populated _RapidOcrModelSpec.

    - Prefer PP-OCRv6 (whose recognizer is multilingual and covers ~52 codes)
    - Otherwise fall back to PP-OCRv4 for the torch backend or PP-OCRv5 for the others.
    - Raises when the language cannot be served by the resolved backbone.

    Callers pass a single language; reducing a multi-language request is up to them.
    """
    from rapidocr.utils.model_resolver import COMMON_LANG_ALIASES, PP_OCRV6_LANGS
    from rapidocr.utils.typings import OCRVersion

    code = lang.strip().lower()

View on GitHub (pinned to 61d76f1ff3)

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.

Example fix

# before
ocr_options = RapidOcrOptions(backend="ort")

# after
ocr_options = RapidOcrOptions(backend="onnxruntime")

Defensive patterns

Strategy: validation

Validate before calling

from docling.models.stages.ocr.rapid_ocr_model import _RAPIDOCR_BACKENDS

backend = "onnxruntime"
assert backend in _RAPIDOCR_BACKENDS, f"backend must be one of {sorted(_RAPIDOCR_BACKENDS)}"

Type guard

def is_valid_rapidocr_backend(backend: str) -> bool:
    from docling.models.stages.ocr.rapid_ocr_model import _RAPIDOCR_BACKENDS
    return backend in _RAPIDOCR_BACKENDS

Try / catch

try:
    ocr = RapidOcrModel(options=RapidOcrOptions(backend=backend))
except ValueError as e:
    if "Unknown RapidOCR backend" in str(e):
        raise ConfigError(f"bad backend {backend!r}: {e}") from e
    raise

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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