docling-project/docling · error · ValueError

RapidOCR torch backend does not support language {lang!r}. S

Error message

RapidOCR torch backend does not support language {lang!r}. Supported: {sorted(PP_OCRV6_LANGS | _PPOCRV4_LANGS)}.

What it means

When resolving the OCR model for a requested language, Docling prefers PP-OCRv6 (multilingual). For the torch backend it can only fall back to PP-OCRv4, so if the language (after Docling normalization and rapidocr COMMON_LANG_ALIASES mapping) is in neither PP_OCRV6_LANGS nor _PPOCRV4_LANGS, this ValueError is raised. The message lists the union of supported codes.

Source

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

    - 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()
    code = _DOCLING_LANG_NORMALIZE.get(code, code)
    aliased = COMMON_LANG_ALIASES.get(code, code)

    if aliased in PP_OCRV6_LANGS:
        version = OCRVersion.PPOCRV6
    elif backend == "torch":
        if aliased not in _PPOCRV4_LANGS:
            raise ValueError(
                f"RapidOCR torch backend does not support language {lang!r}. "
                f"Supported: {sorted(PP_OCRV6_LANGS | _PPOCRV4_LANGS)}."
            )
        version = OCRVersion.PPOCRV4
    elif aliased in _PPOCRV5_LANGS:
        version = OCRVersion.PPOCRV5
    else:
        raise ValueError(
            f"RapidOCR {backend} backend does not support language {lang!r}. "
            f"Supported: {sorted(PP_OCRV6_LANGS | _PPOCRV5_LANGS)}."
        )

    _log.debug(
        "RapidOCR resolved lang=%r backend=%r -> version=%s rec_lang=%r",
        lang,
        backend,
        version.value,
        aliased,

View on GitHub (pinned to 61d76f1ff3)

Solutions

Switch to a non-torch backend such as 'onnxruntime' or 'openvino', which can fall back to PP-OCRv5 and covers more languages.
Verify the language code appears in the sorted list printed in the error; correct typos or use the canonical rapidocr language code.
If the language is genuinely unsupported by RapidOCR, use a different OCR engine (e.g. Tesseract or EasyOCR) via OcrOptions.ocr_engine.

Example fix

# before
ocr_options = RapidOcrOptions(lang="korean", backend="torch")

# after
ocr_options = RapidOcrOptions(lang="korean", backend="onnxruntime")

Defensive patterns

Strategy: validation

Validate before calling

from rapidocr.utils.model_resolver import PP_OCRV6_LANGS
# at startup, before building the pipeline:
if backend == "torch":
    assert aliased_lang in PP_OCRV6_LANGS | _PPOCRV4_LANGS, (
        f"lang {lang!r} unsupported on torch backend; use onnxruntime/openvino"
    )

Try / catch

try:
    pipeline.initialize()
except ValueError as e:
    if "torch backend does not support language" in str(e):
        # degrade to a backend with wider language coverage
        options.backend = "onnxruntime"
        pipeline.initialize()
    else:
        raise

Prevention

Pin the (lang, backend) pairs you support in a config matrix and validate at startup.
Prefer onnxruntime/openvino backends when language coverage matters more than torch execution.
Test each configured language against the actual backend in CI.

When it happens

Trigger: RapidOcrOptions(lang='...', backend='torch') where the language code is not covered by PP-OCRv6 or PP-OCRv4, e.g. a language only served by PP-OCRv5 models (available on onnxruntime/openvino/paddle backends).

Common situations: Users switching to backend='torch' for GPU inference without checking that their language is served; using exotic or regional language codes that only exist in the v5 model family; misspelled language codes that alias-resolution cannot map.

Related errors

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