zylon-ai/private-gpt · error · ValueError

Language {lang} not supported by Tesseract

Error message

Language {lang} not supported by Tesseract

What it means

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.

Source

Thrown at private_gpt/components/readers/docling/utils.py:115

        raise ValueError(f"Language {lang} not supported by EasyOCR") from e


def convert_to_tesseract_lang(lang: str) -> str:
    """Convert language code to Tesseract format.

    Args:
        lang: Language code in format like 'en-US', 'es-ES'

    Returns:
        Language code in Tesseract format (e.g., 'eng', 'spa')

    Raises:
        ValueError: If language is not supported
    """
    try:
        return LANG_TO_TESSERACT[lang]
    except KeyError as e:
        raise ValueError(f"Language {lang} not supported by Tesseract") from e


def convert_to_rapidocr_lang(lang: str) -> str:
    """Convert language code to RapidOCR format.

    Args:
        lang: Language code in format like 'en-US', 'es-ES'

    Returns:
        Language name in RapidOCR format (e.g., 'english', 'chinese')

    Raises:
        ValueError: If language is not supported
    """
    try:
        return LANG_TO_RAPIDOCR[lang]
    except KeyError as e:
        raise ValueError(f"Language {lang} not supported by RapidOCR") from e

View on GitHub (pinned to 4a030776a3)

Solutions

  1. Use the map's key format in docling.langs (check LANG_TO_TESSERACT in utils.py; typically 'en-US' → 'eng').
  2. 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.
  3. Switch ocr_model to another engine if the language is mapped there instead.

Example fix

# settings.yaml — before
# docling:
#   ocr_model: tesseract
#   langs: [eng]

# after
# docling:
#   ocr_model: tesseract
#   langs: [en-US]
Defensive patterns

Strategy: validation

Validate before calling

from private_gpt.components.readers.docling.utils import LANG_TO_TESSERACT

def validate_tesseract_langs(langs: list[str]) -> None:
    bad = [l for l in langs if l not in LANG_TO_TESSERACT]
    if bad:
        raise SystemExit(f"langs {bad} not supported by tesseract mapping: {bad}")

validate_tesseract_langs(settings().docling.langs or [])

Type guard

from private_gpt.components.readers.docling.utils import LANG_TO_TESSERACT

def is_tesseract_lang(lang: str) -> bool:
    return lang in LANG_TO_TESSERACT

Try / catch

try:
    tess = [convert_to_tesseract_lang(l) for l in langs]
except ValueError as e:
    if "not supported by Tesseract" in str(e):
        raise ConfigurationError(str(e)) from e
    raise

Prevention

When it happens

Trigger: 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'.

Common situations: 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.

Related errors

AI-assisted analysis of zylon-ai/private-gpt@4a030776a3 (2026-08-15). Data as JSON: /api/errors/871f717ece496166. Report an issue: GitHub.