What causes "Unsupported EasyOCR language code: {language}" in docling-project/docling?

Use only the ISO 639-1 codes present in the mapping in easyocr_model.py (e.g. 'en', 'fr', 'de', 'ko', 'ta', 'te', 'kn').

docling-project/docling · error · ValueError

Unsupported EasyOCR language code

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.

Solutions

Use only the ISO 639-1 codes present in the mapping in easyocr_model.py (e.g. 'en', 'fr', 'de', 'ko', 'ta', 'te', 'kn').
Strip region subtags: convert 'en-US' to 'en' before configuring.
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

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

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

Prevention

Keep lang lists to short ISO 639-1 codes from the mapping in easyocr_model.py.
Validate the language list against the mapping at config-load time.
Prefer a shared config schema with an enum of supported codes over free strings.

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

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

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