ocrmypdf/OCRmyPDF · error · TypeError

Failed to create OcrOptions for hOCR pipeline: {e}

Error message

Failed to create OcrOptions for hOCR pipeline: {e}

What it means

pdf_to_hocr() forwards your keyword arguments into an OcrOptions dataclass; if any kwarg is not a valid OcrOptions field (or has a wrong type), the constructor raises and it is rewrapped as TypeError with this message so you know which pipeline stage failed.

Source

Thrown at src/ocrmypdf/api.py:981

    ocr_fields = set(OcrOptions.model_fields.keys())
    # Legacy mode flags are handled by OcrOptions model validator
    legacy_mode_flags = {'force_ocr', 'skip_text', 'redo_ocr'}
    known_extra = {'progress_bar', 'plugins'}

    for key in list(options_kwargs.keys()):
        if key in ocr_fields or key in legacy_mode_flags or key in known_extra:
            continue
        extra_attrs[key] = options_kwargs.pop(key)

    with _plugin_session(plugins, plugin_manager) as plugin_manager:
        # Create OcrOptions directly
        try:
            options = OcrOptions(**options_kwargs)
            # Add any extra attributes
            if extra_attrs:
                options.extra_attrs.update(extra_attrs)
        except Exception as e:
            raise TypeError(
                f"Failed to create OcrOptions for hOCR pipeline: {e}"
            ) from e

        return run_hocr_pipeline(options=options, plugin_manager=plugin_manager)


def _hocr_to_ocr_pdf(  # noqa: D417
    work_folder: Path,
    output_file: Path,
    *,
    jobs: int | None = None,
    use_threads: bool | None = None,
    optimize: int | None = None,
    jpeg_quality: int | None = None,
    png_quality: int | None = None,
    jbig2_lossy: bool | None = None,  # Deprecated, ignored
    jbig2_page_group_size: int | None = None,  # Deprecated, ignored
    jbig2_threshold: float | None = None,

View on GitHub (pinned to 5074a0b0e1)

Solutions

1. Check the original TypeError/__cause__ message — it names the invalid argument (e.g. 'unexpected keyword bogus_flag').
2. Correct or remove the offending kwarg; verify field names against OcrOptions for your installed version.

Example fix

# before
pdf_to_hocr(pdf, out, skip_text=True)
# after
pdf_to_hocr(pdf, out, mode=ProcessingMode.skip)  # or use the correct field name

from ocrmypdf._options import OcrOptions  # or ocrmypdf.OcrOptions
valid = set(OcrOptions.__dataclass_fields__)
bad = set(kwargs) - valid
assert not bad, f'unknown OcrOptions fields: {bad}'

def is_valid_hocr_kwargs(kwargs: dict) -> bool:
    return set(kwargs) <= set(OcrOptions.__dataclass_fields__)

try:
    pdf_to_hocr(...)
except TypeError as e:
    if 'Failed to create OcrOptions' in str(e):
        bad = e.__cause__  # names the invalid argument
        raise ValueError(str(bad)) from e
    raise

When it happens

Trigger: Calling pdf_to_hocr(..., language='eng', bogus_flag=True) or passing a wrong type like rotate='x' — any kwarg OcrOptions rejects.

Common situations: Using old CLI flag names as kwargs (--skip-text vs skip_text), typos in option names, or copying options from a different ocrmypdf version whose OcrOptions fields changed.

Related errors

• Failed to create OcrOptions for hOCR to PDF pipeline: {e}
• --redo-ocr (or --mode redo) is not currently compatible with
• Since you specified `--output-type none`, the output file {s
• Input file is an image, but the resolution (DPI) is not cred
• Input file is an image, but has no resolution (DPI) in its m

AI-assisted analysis of ocrmypdf/OCRmyPDF@5074a0b0e1 (2026-08-27). Data as JSON: /api/errors/364e438e4f39b7ec. Report an issue: GitHub.