zylon-ai/private-gpt · error · ValueError

Language {lang} not supported by EasyOCR

Error message

Language {lang} not supported by EasyOCR

What it means

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__.

Source

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

}


def convert_to_easyocr_lang(lang: str) -> str:
    """Convert language code to EasyOCR format.

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

    Returns:
        Language code in EasyOCR format (e.g., 'en', 'es')

    Raises:
        ValueError: If language is not supported
    """
    try:
        return LANG_TO_EASYOCR[lang]
    except KeyError as e:
        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

View on GitHub (pinned to 4a030776a3)

Solutions

  1. 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).
  2. If you wrote tesseract codes by mistake, translate them: 'eng' → 'en-US', 'spa' → 'es-ES'.
  3. If the language is genuinely unsupported by EasyOCR, switch ocr_model to an engine that supports it (tesseract/rapidocr) or drop the language.
  4. Validate langs at startup (see defense) so misconfiguration surfaces before ingestion.

Example fix

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

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

Strategy: validation

Validate before calling

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

def validate_easyocr_langs(langs: list[str]) -> None:
    bad = [l for l in langs if l not in LANG_TO_EASYOCR]
    if bad:
        raise SystemExit(f"langs {bad} not supported by easyocr; valid keys: {sorted(LANG_TO_EASYOCR)[:20]}...")

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

Type guard

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

def is_easyocr_lang(lang: str) -> bool:
    return lang in LANG_TO_EASYOCR

Try / catch

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

try:
    easy = [convert_to_easyocr_lang(l) for l in langs]
except ValueError as e:
    if "not supported by EasyOCR" in str(e):
        raise ConfigurationError(f"adjust docling.langs: {e}") from e
    raise

Prevention

When it happens

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

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

Related errors

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