ocrmypdf/OCRmyPDF · error · TypeError

Failed to create OcrOptions for hOCR to PDF pipeline

Error message

Failed to create OcrOptions for hOCR to PDF pipeline: {e}

What it means

hocr_to_ocr_pdf() builds an OcrOptions from your kwargs before running the PDF-assembly stage; invalid or mistyped kwargs make the OcrOptions constructor fail, which is wrapped in this TypeError identifying the stage.

Solutions

1. Inspect the chained cause exception for the exact invalid argument.
2. Fix the kwarg name/type to match OcrOptions fields, or drop it.

Example fix

# before
hocr_to_ocr_pdf(work, out, output_type='pdfa')  # wrong name for this API
# after
hocr_to_ocr_pdf(work, out)  # or pass only kwargs OcrOptions accepts

bad = set(kwargs) - set(OcrOptions.__dataclass_fields__)
assert not bad, f'unknown OcrOptions fields: {bad}'

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

try:
    hocr_to_ocr_pdf(...)
except TypeError as e:
    if 'Failed to create OcrOptions' in str(e):
        raise ValueError(str(e.__cause__)) from e
    raise

When it happens

Trigger: Calling hocr_to_ocr_pdf(work, out, pdfa=False, typo_option=1) — any kwarg not accepted by OcrOptions.

Common situations: Passing output-type or renderer flags with wrong names/types when assembling the OCR'd PDF; version drift changing available OcrOptions fields.

Related errors

• Failed to create OcrOptions for hOCR pipeline
• A worker process lost access to an input file
• A worker process lost access to an input file
• At least one provider is required
• --clean is required for --unpaper-args

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

Appendix: source

Thrown at src/ocrmypdf/api.py:1090

    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 to PDF pipeline: {e}"
            ) from e

        return run_hocr_to_ocr_pdf_pipeline(
            options=options, plugin_manager=plugin_manager
        )


__all__ = [
    'PageNumberFilter',
    'Verbosity',
    'check_options',
    'configure_logging',
    'configure_stdout_protection',
    'create_options',
    'get_parser',
    'get_plugin_manager',
    'ocr',

View on GitHub (pinned to 5074a0b0e1)