ocrmypdf/OCRmyPDF · error · TypeError

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

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.

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)

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: {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/4ba101133c7e8d8a. Report an issue: GitHub.