opendataloader-project/opendataloader-pdf · error · ValueError

Unknown ocr_engine '{ocr_engine}': {e}\nAvailable engines: {

Error message

Unknown ocr_engine '{ocr_engine}': {e}\nAvailable engines: {available}

What it means

ValueError raised when ocr_factory.create_options(kind=ocr_engine, ...) threw a RuntimeError because the engine name is genuinely unknown/unregistered to docling's factory (not merely denylisted — that is error 94). The original RuntimeError is chained (raise ... from e) and the message lists the engines that ARE available after subtracting the denylist, so the caller can pick a valid one.

Source

Thrown at python/opendataloader-pdf/src/opendataloader_pdf/hybrid_server.py:463

        # so enforce the denylist here too. Without this, the module-level claim
        # that `_OCR_ENGINE_DENYLIST` is shared across CLI and create_converter
        # would only be true at the CLI layer.
        available = sorted(set(ocr_factory.registered_kind) - _OCR_ENGINE_DENYLIST)
        raise ValueError(
            f"OCR engine '{ocr_engine}' is not supported in hybrid local mode "
            f"(filtered by _OCR_ENGINE_DENYLIST). Available engines: {available}"
        )
    try:
        ocr_options = ocr_factory.create_options(
            kind=ocr_engine,
            force_full_page_ocr=force_full_page_ocr,
        )
    except RuntimeError as e:
        # Library-friendly error type so programmatic callers can catch and retry
        # with a different engine. main() relies on argparse `choices` to gate
        # invalid CLI input, so this branch is reached only via direct calls.
        available = sorted(set(ocr_factory.registered_kind) - _OCR_ENGINE_DENYLIST)
        raise ValueError(
            f"Unknown ocr_engine '{ocr_engine}': {e}\nAvailable engines: {available}"
        ) from e

    if ocr_lang:
        ocr_options.lang = ocr_lang

    # Tesseract-only: Page Segmentation Mode
    if psm is not None and isinstance(
        ocr_options, (TesseractOcrOptions, TesseractCliOcrOptions)
    ):
        ocr_options.psm = psm

    # Configure picture description options with custom prompt.
    # When picture_description_prompt is None or blank, omit the field so
    # docling's built-in default prompt is used. A blank string would otherwise
    # silently produce empty-prompt output — same class of silent-flag bug
    # as PDFDLOSP-20 reported.
    picture_description_options = None

View on GitHub (pinned to a7789b8e77)

Solutions

  1. Pick an engine from the 'Available engines' list in the error message.
  2. Install the engine's extra package if it is optional (e.g. the tesseract system binary or the easyocr/torch extras) so docling registers it.
  3. Fix typos in the engine name and match docling's registered kind exactly.
  4. After upgrading docling, re-check registered engines: python -c "from docling.models.factories import get_ocr_factory; print(get_ocr_factory(allow_external_plugins=False).registered_kind)".

Example fix

# before: typo / unregistered engine
create_converter(ocr_engine='tessaract')  # -> ValueError: Unknown ocr_engine
# after: correct registered name
create_converter(ocr_engine='tesseract')
Defensive patterns

Strategy: validation

Validate before calling

from docling.models.factories import get_ocr_factory
from opendataloader_pdf.hybrid_server import _OCR_ENGINE_DENYLIST
def is_known_engine(engine: str) -> bool:
    factory = get_ocr_factory(allow_external_plugins=False)
    return engine in (set(factory.registered_kind) - _OCR_ENGINE_DENYLIST)

Type guard

def is_unknown_engine_error(exc: ValueError) -> bool:
    return isinstance(exc, ValueError) and "Unknown ocr_engine" in str(exc)

Try / catch

try:
    create_converter(ocr_engine=engine)
except ValueError as e:
    if "Unknown ocr_engine" in str(e):
        # message lists available engines; fall back to one
        engine = "auto"
        create_converter(ocr_engine=engine)
    raise

Prevention

When it happens

Trigger: Calling create_converter with an ocr_engine that is neither denied (error 94) nor registered in docling's ocr_factory — a typo, an engine whose plugin/package is not installed, or an engine renamed in a newer docling version.

Common situations: Typo in the engine name ('tessaract' vs 'tesseract'). The engine's extra package was never installed so docling did not register it. A docling upgrade renamed or removed an engine. A caller uses an engine valid in a different docling version.

Related errors

AI-assisted analysis of opendataloader-project/opendataloader-pdf@a7789b8e77 (2026-08-14). Data as JSON: /api/errors/de1f733890b1f919. Report an issue: GitHub.