{"record":{"id":"871f717ece496166","repo":"zylon-ai/private-gpt","slug":"language-lang-not-supported-by-tesseract","errorCode":null,"errorMessage":"Language {lang} not supported by Tesseract","messagePattern":"Language (.+?) not supported by Tesseract","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"private_gpt/components/readers/docling/utils.py","lineNumber":115,"sourceCode":"        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\n\n\ndef convert_to_rapidocr_lang(lang: str) -> str:\n    \"\"\"Convert language code to RapidOCR format.\n\n    Args:\n        lang: Language code in format like 'en-US', 'es-ES'\n\n    Returns:\n        Language name in RapidOCR format (e.g., 'english', 'chinese')\n\n    Raises:\n        ValueError: If language is not supported\n    \"\"\"\n    try:\n        return LANG_TO_RAPIDOCR[lang]\n    except KeyError as e:\n        raise ValueError(f\"Language {lang} not supported by RapidOCR\") from e","sourceCodeStart":97,"sourceCodeEnd":133,"githubUrl":"https://github.com/zylon-ai/private-gpt/blob/4a030776a31a901ad80b1bf4d7faa2c1a367efbb/private_gpt/components/readers/docling/utils.py#L97-L133","documentation":"Raised by convert_to_tesseract_lang in docling/utils.py when the language code is not a key of LANG_TO_TESSERACT. With ocr_model: tesseract, docling.langs entries (BCP-47 style like 'en-US') are mapped to Tesseract's three-letter codes ('eng', 'spa'); an unknown key aborts before any request. The chained KeyError identifies the exact missing code.","triggerScenarios":"settings.docling.langs containing a code not in LANG_TO_TESSERACT — e.g., already-Tesseract codes ('eng') where 'en-US' is expected, or a language whose Tesseract data pack you assume exists but the map does not include — while ocr_model is 'tesseract'.","commonSituations":"Users pasting Tesseract codes directly into langs (double-mapping confusion); languages where a Tesseract traineddata exists upstream but private-gpt's map was not updated; switching ocr_model from easyocr to tesseract and assuming codes carry over.","solutions":["Use the map's key format in docling.langs (check LANG_TO_TESSERACT in utils.py; typically 'en-US' → 'eng').","If the code is right but you need an exotic language, add the mapping via a small patch/PR extending LANG_TO_TESSERACT — and ensure the server image has the traineddata installed.","Switch ocr_model to another engine if the language is mapped there instead."],"exampleFix":"# settings.yaml — before\n# docling:\n#   ocr_model: tesseract\n#   langs: [eng]\n\n# after\n# docling:\n#   ocr_model: tesseract\n#   langs: [en-US]","handlingStrategy":"validation","validationCode":"from private_gpt.components.readers.docling.utils import LANG_TO_TESSERACT\n\ndef validate_tesseract_langs(langs: list[str]) -> None:\n    bad = [l for l in langs if l not in LANG_TO_TESSERACT]\n    if bad:\n        raise SystemExit(f\"langs {bad} not supported by tesseract mapping: {bad}\")\n\nvalidate_tesseract_langs(settings().docling.langs or [])","typeGuard":"from private_gpt.components.readers.docling.utils import LANG_TO_TESSERACT\n\ndef is_tesseract_lang(lang: str) -> bool:\n    return lang in LANG_TO_TESSERACT","tryCatchPattern":"try:\n    tess = [convert_to_tesseract_lang(l) for l in langs]\nexcept ValueError as e:\n    if \"not supported by Tesseract\" in str(e):\n        raise ConfigurationError(str(e)) from e\n    raise","preventionTips":["When switching ocr_model, re-check every entry in docling.langs against the new engine's map.","Remember the mapping direction: settings hold 'en-US'-style codes, the engine gets 'eng'."],"tags":["docling","ocr","tesseract","language-codes","configuration"],"backgroundTag":null,"analyzedSha":"4a030776a31a901ad80b1bf4d7faa2c1a367efbb","analyzedAt":"2026-08-15T03:51:26.951Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}