{"record":{"id":"b47e3d91bf3aecfe","repo":"zylon-ai/private-gpt","slug":"language-lang-not-supported-by-easyocr","errorCode":null,"errorMessage":"Language {lang} not supported by EasyOCR","messagePattern":"Language (.+?) not supported by EasyOCR","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"private_gpt/components/readers/docling/utils.py","lineNumber":97,"sourceCode":"}\n\n\ndef convert_to_easyocr_lang(lang: str) -> str:\n    \"\"\"Convert language code to EasyOCR format.\n\n    Args:\n        lang: Language code in format like 'en-US', 'es-ES'\n\n    Returns:\n        Language code in EasyOCR format (e.g., 'en', 'es')\n\n    Raises:\n        ValueError: If language is not supported\n    \"\"\"\n    try:\n        return LANG_TO_EASYOCR[lang]\n    except KeyError as e:\n        raise ValueError(f\"Language {lang} not supported by EasyOCR\") from e\n\n\ndef convert_to_tesseract_lang(lang: str) -> str:\n    \"\"\"Convert language code to Tesseract format.\n\n    Args:\n        lang: Language code in format like 'en-US', 'es-ES'\n\n    Returns:\n        Language code in Tesseract format (e.g., 'eng', 'spa')\n\n    Raises:\n        ValueError: If language is not supported\n    \"\"\"\n    try:\n        return LANG_TO_TESSERACT[lang]\n    except KeyError as e:\n        raise ValueError(f\"Language {lang} not supported by Tesseract\") from e","sourceCodeStart":79,"sourceCodeEnd":115,"githubUrl":"https://github.com/zylon-ai/private-gpt/blob/4a030776a31a901ad80b1bf4d7faa2c1a367efbb/private_gpt/components/readers/docling/utils.py#L79-L115","documentation":"Raised by convert_to_easyocr_lang in private_gpt/components/readers/docling/utils.py when the given language code is not a key of the LANG_TO_EASYOCR mapping. Docling is configured with codes like 'en-US'/'es-ES' (BCP-47 style) and each OCR engine needs its own format ('en', 'es' for EasyOCR); an unmapped code means the configuration value was never in the supported set. The original KeyError is chained as __cause__.","triggerScenarios":"settings.docling.langs containing a code absent from LANG_TO_EASYOCR — e.g., 'en' (bare code where 'en-US' is expected, or vice versa), a three-letter code like 'eng', or a language EasyOCR does not support — while ocr_model is 'easyocr' (the default). Fires during get_ocr_langs() at payload construction.","commonSituations":"Copying tesseract-style codes ('eng', 'spa') into docling.langs; using bare codes ('en') where the map keys are hyphenated ('en-US'); minor/exotic languages unsupported by EasyOCR; switching ocr_model without updating the langs values.","solutions":["Check the LANG_TO_EASYOCR keys in private_gpt/components/readers/docling/utils.py and use exactly those codes in docling.langs (typically 'en-US' style).","If you wrote tesseract codes by mistake, translate them: 'eng' → 'en-US', 'spa' → 'es-ES'.","If the language is genuinely unsupported by EasyOCR, switch ocr_model to an engine that supports it (tesseract/rapidocr) or drop the language.","Validate langs at startup (see defense) so misconfiguration surfaces before ingestion."],"exampleFix":"# settings.yaml — before\n# docling:\n#   langs: [eng]\n\n# after\n# docling:\n#   langs: [en-US]","handlingStrategy":"validation","validationCode":"from private_gpt.components.readers.docling.utils import LANG_TO_EASYOCR\n\ndef validate_easyocr_langs(langs: list[str]) -> None:\n    bad = [l for l in langs if l not in LANG_TO_EASYOCR]\n    if bad:\n        raise SystemExit(f\"langs {bad} not supported by easyocr; valid keys: {sorted(LANG_TO_EASYOCR)[:20]}...\")\n\nvalidate_easyocr_langs(settings().docling.langs or [])","typeGuard":"from private_gpt.components.readers.docling.utils import LANG_TO_EASYOCR\n\ndef is_easyocr_lang(lang: str) -> bool:\n    return lang in LANG_TO_EASYOCR","tryCatchPattern":"from private_gpt.components.readers.docling.utils import convert_to_easyocr_lang\n\ntry:\n    easy = [convert_to_easyocr_lang(l) for l in langs]\nexcept ValueError as e:\n    if \"not supported by EasyOCR\" in str(e):\n        raise ConfigurationError(f\"adjust docling.langs: {e}\") from e\n    raise","preventionTips":["Validate docling.langs against the target engine's map at startup, before ingestion starts.","Use the map keys' format (BCP-47 style like 'en-US'), never engine-native codes like 'eng'."],"tags":["docling","ocr","easyocr","language-codes","configuration"],"backgroundTag":null,"analyzedSha":"4a030776a31a901ad80b1bf4d7faa2c1a367efbb","analyzedAt":"2026-08-15T03:51:26.951Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}