docling-project/docling · error · ValueError

RapidOCR {backend} backend does not support language {lang!r

Error message

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

What it means

For non-torch backends the language resolver falls back from PP-OCRv6 to PP-OCRv5. If the requested language (after normalization and aliasing) is in neither PP_OCRV6_LANGS nor _PPOCRV5_LANGS, this ValueError is raised listing the supported codes for this backend.

Source

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

    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,
    )
    return _RapidOcrModelSpec(
        backend=backend,
        user_lang=lang,
        rapidocr_lang_token=aliased,
        ppocr_version=version,
    )

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Use one of the language codes listed in the error message (they are the exact accepted tokens after aliasing).
2. Check Docling's _DOCLING_LANG_NORMALIZE and rapidocr's COMMON_LANG_ALIASES to confirm your spelling maps correctly.
3. If the language is unsupported by RapidOCR entirely, select a different OCR engine via pipeline_options.ocr_options.

Example fix

# before
ocr_options = RapidOcrOptions(lang="jpan")

# after
ocr_options = RapidOcrOptions(lang="japan")

from rapidocr.utils.model_resolver import COMMON_LANG_ALIASES, PP_OCRV6_LANGS

code = lang.strip().lower()
aliased = COMMON_LANG_ALIASES.get(code, code)
assert aliased in PP_OCRV6_LANGS | _PPOCRV5_LANGS, f"unsupported lang {lang!r}"

def is_supported_rapidocr_lang(lang: str) -> bool:
    from rapidocr.utils.model_resolver import COMMON_LANG_ALIASES, PP_OCRV6_LANGS
    code = lang.strip().lower()
    aliased = COMMON_LANG_ALIASES.get(code, code)
    return aliased in PP_OCRV6_LANGS  # v6 is the preferred superset

try:
    RapidOcrModel(options=RapidOcrOptions(lang=lang, backend=backend))
except ValueError as e:
    if "does not support language" in str(e):
        log.warning("unsupported lang %r, falling back to default OCR language", lang)
        options.lang = ["en"]
    else:
        raise

When it happens

Trigger: RapidOcrOptions(lang=X, backend='onnxruntime'|'openvino'|'paddle') where X is not a PP-OCRv5 or PP-OCRv6 language code, e.g. a fabricated code like 'klingon' or an unsupported regional code.

Common situations: Misspelled language codes ('ch' vs 'chinese'); using ISO codes that rapidocr does not alias; assuming a language is supported because another OCR engine supports it.

Related errors

• Invalid RapidOCR model spec {value!r}: {err}
• Unsupported EasyOCR language code: {language}
• Invalid RapidOCR model spec {value!r}. Expected '<backend>:<
• Unknown RapidOCR backend {backend!r} in {value!r}. Supported
• Unknown RapidOCR backend {backend!r}. Supported: {list(_RAPI

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