zylon-ai/private-gpt · error · ValueError

OCR model {settings().docling.ocr_model} not supported

Error message

OCR model {settings().docling.ocr_model} not supported

What it means

Raised by get_ocr_langs() when settings().docling.ocr_model is not one of the four supported OCR engines: easyocr, tesseract, rapidocr, ocrmac. The function then maps each language code to the engine-specific format via the LANG_TO_* dictionaries in utils.py, so an unknown engine has no mapping path. In stock builds the settings model already constrains ocr_model with a Literal type, so this branch is a defensive backstop that mainly fires when settings are injected or constructed without full validation.

Source

Thrown at private_gpt/components/readers/docling/common.py:40

    """Get the OCR languages.

    Returns:
        list[str]: List of OCR languages.
    """
    langs: list[str] | None = settings().docling.langs
    if not langs:
        raise ValueError("No OCR languages specified.")
    match settings().docling.ocr_model:
        case "easyocr":
            langs = [convert_to_easyocr_lang(lang) for lang in langs]
        case "tesseract":
            langs = [convert_to_tesseract_lang(lang) for lang in langs]
        case "rapidocr":
            langs = [convert_to_rapidocr_lang(lang) for lang in langs]
        case "ocrmac":
            langs = [convert_to_ocrmac_lang(lang) for lang in langs]
        case _:
            raise ValueError(f"OCR model {settings().docling.ocr_model} not supported")
    return langs


async def calculate_file_priority(
    file_bytes: bytes, pages: int | None = None, **kwargs: Any
) -> int:
    """Calculate processing priority based on file size and page count.

    Priority levels:
    - 0: High priority (small files < 1MB and <= 100 pages)
    - 1: Low priority (files > 10MB or > 50 pages)
    """
    file_size = len(file_bytes)

    # High priority: files under 1MB
    if file_size < 1_000_000 and (pages is None or pages <= 100):
        return 0

View on GitHub (pinned to 4a030776a3)

Solutions

  1. Set ocr_model to one of the four supported values in settings.yaml: easyocr, tesseract, rapidocr, or ocrmac.
  2. Check for typos in the docling.ocr_model key (e.g., 'tessaract', 'EasyOCR').
  3. If you construct DoclingConfig in code, validate it (model_validate) so Literal constraints catch bad values at construction instead of at conversion time.
  4. Pick ocrmac only on macOS (it wraps Apple's Vision framework); pick tesseract only if the server image has tesseract installed.

Example fix

# settings.yaml — before
# docling:
#   ocr_model: easy-ocr

# after
# docling:
#   ocr_model: easyocr
Defensive patterns

Strategy: validation

Validate before calling

SUPPORTED_OCR = {"easyocr", "tesseract", "rapidocr", "ocrmac"}

def validate_ocr_engine(cfg) -> None:
    if cfg.use_ocr and cfg.ocr_model not in SUPPORTED_OCR:
        raise SystemExit(f"docling.ocr_model must be one of {sorted(SUPPORTED_OCR)}")

validate_ocr_engine(settings().docling)

Type guard

def is_supported_ocr_model(model: str) -> bool:
    return model in {"easyocr", "tesseract", "rapidocr", "ocrmac"}

Try / catch

try:
    langs = get_ocr_langs()
except ValueError as e:
    if "not supported" in str(e) and "OCR model" in str(e):
        raise ConfigurationError(str(e)) from e  # config bug: fail fast, no retry
    raise

Prevention

When it happens

Trigger: settings.docling.ocr_model set to anything other than 'easyocr', 'tesseract', 'rapidocr', or 'ocrmac' while OCR language conversion runs. Because DoclingSettings declares ocr_model: Literal[...], the typical trigger is a programmatically built/unvalidated DoclingConfig, a plugin-supplied settings object, or a settings loader that bypasses Literal validation.

Common situations: Typos in settings.yaml like 'tessaract' or 'easy-ocr' (usually caught earlier by pydantic Literal validation — if you see this error instead, your settings path skipped validation); upgrading private-gpt where the supported engine list changed; custom builds adding an engine name without registering a language map.

Related errors

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