{"record":{"id":"a76c951f709c9fe5","repo":"docling-project/docling","slug":"unsupported-easyocr-language-code-language","errorCode":null,"errorMessage":"Unsupported EasyOCR language code: {language}","messagePattern":"Unsupported EasyOCR language code: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/models/stages/ocr/easyocr_model.py","lineNumber":67,"sourceCode":"        {\n            \"en\": \"english_g2\",\n            \"th\": \"thai_g1\",\n            \"ch_tra\": \"zh_tra_g1\",\n            \"ch_sim\": \"zh_sim_g2\",\n            \"ja\": \"japanese_g2\",\n            \"ko\": \"korean_g2\",\n            \"ta\": \"tamil_g1\",\n            \"te\": \"telugu_g2\",\n            \"kn\": \"kannada_g2\",\n        }\n    )\n\n    model_names: List[str] = []\n    for language in languages:\n        try:\n            model_name = language_models[language]\n        except KeyError:\n            raise ValueError(f\"Unsupported EasyOCR language code: {language}\") from None\n        if model_name not in model_names:\n            model_names.append(model_name)\n    return model_names\n\n\nclass EasyOcrModel(BaseOcrModel):\n    _model_repo_folder = \"EasyOcr\"\n\n    def __init__(\n        self,\n        enabled: bool,\n        artifacts_path: Optional[Path],\n        options: EasyOcrOptions,\n        accelerator_options: AcceleratorOptions,\n    ):\n        super().__init__(\n            enabled=enabled,\n            artifacts_path=artifacts_path,","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/stages/ocr/easyocr_model.py#L49-L85","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\noptions = EasyOcrOptions(lang=[\"en-US\", \"zh-CN\"])\n\n# after\noptions = EasyOcrOptions(lang=[\"en\", \"ch_sim\"])  # codes from the supported mapping","handlingStrategy":"validation","validationCode":"from docling.models.stages.ocr.easyocr_model import _get_easyocr_model_names\ntry:\n    _get_easyocr_model_names(options.lang)\nexcept ValueError as err:\n    print(err)  # fix lang list before building the pipeline","typeGuard":"def is_supported_easyocr_lang(lang: str, mapping_keys: set[str]) -> bool:\n    return lang in mapping_keys","tryCatchPattern":"try:\n    pipeline = DocumentConverter(format_options={\"pdf\": PdfFormatOptions(ocr_options=options)})\nexcept ValueError as err:\n    if \"Unsupported EasyOCR language code\" in str(err):\n        # correct options.lang and rebuild\n        ...\n    raise","preventionTips":["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."],"tags":["easyocr","ocr","language","validation"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}