docling-project/docling · error · ValueError

Unsupported EasyOCR language code: {language}

Error message

Unsupported EasyOCR language code: {language}

What it means

Docling maps ISO-style language codes to EasyOCR model names through a fixed dictionary (e.g. 'en' -> an English model). When _get_easyocr_model_names receives a language code not present in that mapping, it raises ValueError with the offending code. The accepted set is limited to the languages for which EasyOCR ships models.

Source

Thrown at docling/models/stages/ocr/easyocr_model.py:67

        {
            "en": "english_g2",
            "th": "thai_g1",
            "ch_tra": "zh_tra_g1",
            "ch_sim": "zh_sim_g2",
            "ja": "japanese_g2",
            "ko": "korean_g2",
            "ta": "tamil_g1",
            "te": "telugu_g2",
            "kn": "kannada_g2",
        }
    )

    model_names: List[str] = []
    for language in languages:
        try:
            model_name = language_models[language]
        except KeyError:
            raise ValueError(f"Unsupported EasyOCR language code: {language}") from None
        if model_name not in model_names:
            model_names.append(model_name)
    return model_names


class EasyOcrModel(BaseOcrModel):
    _model_repo_folder = "EasyOcr"

    def __init__(
        self,
        enabled: bool,
        artifacts_path: Optional[Path],
        options: EasyOcrOptions,
        accelerator_options: AcceleratorOptions,
    ):
        super().__init__(
            enabled=enabled,
            artifacts_path=artifacts_path,

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Use only the ISO 639-1 codes present in the mapping in easyocr_model.py (e.g. 'en', 'fr', 'de', 'ko', 'ta', 'te', 'kn').
2. Strip region subtags: convert 'en-US' to 'en' before configuring.
3. If the language is genuinely unsupported by EasyOCR, switch the OCR engine (e.g. Tesseract or RapidOCR) that covers it.

Example fix

# before
options = EasyOcrOptions(lang=["en-US", "zh-CN"])

# after
options = EasyOcrOptions(lang=["en", "ch_sim"])  # codes from the supported mapping

from docling.models.stages.ocr.easyocr_model import _get_easyocr_model_names
try:
    _get_easyocr_model_names(options.lang)
except ValueError as err:
    print(err)  # fix lang list before building the pipeline

def is_supported_easyocr_lang(lang: str, mapping_keys: set[str]) -> bool:
    return lang in mapping_keys

try:
    pipeline = DocumentConverter(format_options={"pdf": PdfFormatOptions(ocr_options=options)})
except ValueError as err:
    if "Unsupported EasyOCR language code" in str(err):
        # correct options.lang and rebuild
        ...
    raise

When it happens

Trigger: Passing OcrOptions.lang or lang list values like 'zz', 'xx', a full locale ('en-US'), or a language EasyOCR does not support (e.g. some regional codes) to the EasyOCR stage; typos in the lang configuration.

Common situations: Copy-pasting locale codes (en-GB, zh-CN) instead of the short codes docling expects; requesting a language EasyOCR never had; configuration files carried over from a different OCR engine (Tesseract codes) whose code set differs.

Related errors

• Invalid RapidOCR model spec {value!r}: {err}
• RapidOCR {backend} backend does not support language {lang!r
• Cannot specify both ocr_preset and ocr_custom_config.
• EasyOCR is not installed. Please install it via `pip install
• Invalid RapidOCR model spec {value!r}. Expected '<backend>:<

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