zylon-ai/private-gpt · error · ValueError

No OCR languages specified.

Error message

No OCR languages specified.

What it means

Raised by get_ocr_langs() in private_gpt/components/readers/docling/common.py when settings().docling.langs is empty/None. OCR language lists are needed to build the conversion options sent to Docling (ocr_lang), and this function deliberately refuses to guess a default: no langs means OCR cannot be configured, so it aborts before any request is made.

Source

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

# Constants
DEFAULT_IMAGE_PLACEHOLDER = "<!-- image -->"
EMBEDDED_IMAGES = settings().docling.image_mode == "embedded"
IMAGE_DUMMY = IMAGE_PLACEHOLDER
IMAGE_RESOLUTION_SCALE = 2.0

PAGE_PLACEHOLDER = "\n<!-- page -->\n"


def get_ocr_langs() -> list[str] | None:
    """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.

View on GitHub (pinned to 4a030776a3)

Solutions

  1. Add langs to the docling section of settings.yaml, e.g. langs: [en] or langs: [en, es].
  2. If you do not want OCR at all, set use_ocr: false so the OCR language path is not exercised.
  3. Verify with a startup assertion: check settings().docling.langs is non-empty before starting ingestion workers.

Example fix

# settings.yaml — before
# docling:
#   api_base: http://localhost:5001

# after
# docling:
#   api_base: http://localhost:5001
#   langs: [en]
Defensive patterns

Strategy: validation

Validate before calling

from private_gpt.settings.settings import settings

def validate_ocr_settings() -> None:
    d = settings().docling
    if d.use_ocr and not d.langs:
        raise SystemExit("docling.langs must be set when docling.use_ocr is true")

validate_ocr_settings()

Try / catch

try:
    langs = get_ocr_langs()
except ValueError as e:
    if "No OCR languages" in str(e):
        langs = ["en"]  # only if a default is acceptable for your deployment
    else:
        raise

Prevention

When it happens

Trigger: Any docling conversion path that calls get_ocr_langs() (option building for OCR-enabled conversion) while settings.docling.langs is unset or an empty list in settings.yaml. Fires before any network I/O, at payload-construction time.

Common situations: A settings.yaml that customizes the docling block (e.g., sets use_ocr: true, ocr_model) but omits langs; deployments relying on a default that does not exist for langs; trimming config down for a minimal install and accidentally dropping the langs key.

Related errors

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