{"record":{"id":"4ba101133c7e8d8a","repo":"ocrmypdf/OCRmyPDF","slug":"failed-to-create-ocroptions-for-hocr-to-pdf-pipeli","errorCode":null,"errorMessage":"Failed to create OcrOptions for hOCR to PDF pipeline: {e}","messagePattern":"Failed to create OcrOptions for hOCR to PDF pipeline: (.+?)","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"src/ocrmypdf/api.py","lineNumber":1090,"sourceCode":"    ocr_fields = set(OcrOptions.model_fields.keys())\n    # Legacy mode flags are handled by OcrOptions model validator\n    legacy_mode_flags = {'force_ocr', 'skip_text', 'redo_ocr'}\n    known_extra = {'progress_bar', 'plugins'}\n\n    for key in list(options_kwargs.keys()):\n        if key in ocr_fields or key in legacy_mode_flags or key in known_extra:\n            continue\n        extra_attrs[key] = options_kwargs.pop(key)\n\n    with _plugin_session(plugins, plugin_manager) as plugin_manager:\n        # Create OcrOptions directly\n        try:\n            options = OcrOptions(**options_kwargs)\n            # Add any extra attributes\n            if extra_attrs:\n                options.extra_attrs.update(extra_attrs)\n        except Exception as e:\n            raise TypeError(\n                f\"Failed to create OcrOptions for hOCR to PDF pipeline: {e}\"\n            ) from e\n\n        return run_hocr_to_ocr_pdf_pipeline(\n            options=options, plugin_manager=plugin_manager\n        )\n\n\n__all__ = [\n    'PageNumberFilter',\n    'Verbosity',\n    'check_options',\n    'configure_logging',\n    'configure_stdout_protection',\n    'create_options',\n    'get_parser',\n    'get_plugin_manager',\n    'ocr',","sourceCodeStart":1072,"sourceCodeEnd":1108,"githubUrl":"https://github.com/ocrmypdf/OCRmyPDF/blob/5074a0b0e109362422b768fd271ed84bf717c4ec/src/ocrmypdf/api.py#L1072-L1108","documentation":"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.","triggerScenarios":"Calling hocr_to_ocr_pdf(work, out, pdfa=False, typo_option=1) — any kwarg not accepted by OcrOptions.","commonSituations":"Passing output-type or renderer flags with wrong names/types when assembling the OCR'd PDF; version drift changing available OcrOptions fields.","solutions":["Inspect the chained cause exception for the exact invalid argument.","Fix the kwarg name/type to match OcrOptions fields, or drop it."],"exampleFix":"# before\nhocr_to_ocr_pdf(work, out, output_type='pdfa')  # wrong name for this API\n# after\nhocr_to_ocr_pdf(work, out)  # or pass only kwargs OcrOptions accepts","handlingStrategy":"type-guard","validationCode":"bad = set(kwargs) - set(OcrOptions.__dataclass_fields__)\nassert not bad, f'unknown OcrOptions fields: {bad}'","typeGuard":"def is_valid_hocr_to_pdf_kwargs(kwargs: dict) -> bool:\n    return set(kwargs) <= set(OcrOptions.__dataclass_fields__)","tryCatchPattern":"try:\n    hocr_to_ocr_pdf(...)\nexcept TypeError as e:\n    if 'Failed to create OcrOptions' in str(e):\n        raise ValueError(str(e.__cause__)) from e\n    raise","preventionTips":["Validate kwargs against OcrOptions for the installed ocrmypdf version.","Pin the ocrmypdf version so option names can't drift under you."],"tags":["ocrmypdf","hocr","options","typeerror"],"backgroundTag":"invalid-constructor-arguments","analyzedSha":"5074a0b0e109362422b768fd271ed84bf717c4ec","analyzedAt":"2026-08-27T11:57:38.523Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}