{"record":{"id":"364e438e4f39b7ec","repo":"ocrmypdf/OCRmyPDF","slug":"failed-to-create-ocroptions-for-hocr-pipeline-e","errorCode":null,"errorMessage":"Failed to create OcrOptions for hOCR pipeline: {e}","messagePattern":"Failed to create OcrOptions for hOCR pipeline: (.+?)","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"src/ocrmypdf/api.py","lineNumber":981,"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 pipeline: {e}\"\n            ) from e\n\n        return run_hocr_pipeline(options=options, plugin_manager=plugin_manager)\n\n\ndef _hocr_to_ocr_pdf(  # noqa: D417\n    work_folder: Path,\n    output_file: Path,\n    *,\n    jobs: int | None = None,\n    use_threads: bool | None = None,\n    optimize: int | None = None,\n    jpeg_quality: int | None = None,\n    png_quality: int | None = None,\n    jbig2_lossy: bool | None = None,  # Deprecated, ignored\n    jbig2_page_group_size: int | None = None,  # Deprecated, ignored\n    jbig2_threshold: float | None = None,","sourceCodeStart":963,"sourceCodeEnd":999,"githubUrl":"https://github.com/ocrmypdf/OCRmyPDF/blob/5074a0b0e109362422b768fd271ed84bf717c4ec/src/ocrmypdf/api.py#L963-L999","documentation":"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.","triggerScenarios":"Calling pdf_to_hocr(..., language='eng', bogus_flag=True) or passing a wrong type like rotate='x' — any kwarg OcrOptions rejects.","commonSituations":"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.","solutions":["Check the original TypeError/__cause__ message — it names the invalid argument (e.g. 'unexpected keyword bogus_flag').","Correct or remove the offending kwarg; verify field names against OcrOptions for your installed version."],"exampleFix":"# before\npdf_to_hocr(pdf, out, skip_text=True)\n# after\npdf_to_hocr(pdf, out, mode=ProcessingMode.skip)  # or use the correct field name","handlingStrategy":"type-guard","validationCode":"from ocrmypdf._options import OcrOptions  # or ocrmypdf.OcrOptions\nvalid = set(OcrOptions.__dataclass_fields__)\nbad = set(kwargs) - valid\nassert not bad, f'unknown OcrOptions fields: {bad}'","typeGuard":"def is_valid_hocr_kwargs(kwargs: dict) -> bool:\n    return set(kwargs) <= set(OcrOptions.__dataclass_fields__)","tryCatchPattern":"try:\n    pdf_to_hocr(...)\nexcept TypeError as e:\n    if 'Failed to create OcrOptions' in str(e):\n        bad = e.__cause__  # names the invalid argument\n        raise ValueError(str(bad)) from e\n    raise","preventionTips":["Validate kwargs against OcrOptions fields before calling.","Print e.__cause__ when this fires — it identifies the exact bad argument."],"tags":["ocrmypdf","hocr","options","typeerror","kwargs"],"backgroundTag":"invalid-constructor-arguments","analyzedSha":"5074a0b0e109362422b768fd271ed84bf717c4ec","analyzedAt":"2026-08-27T11:57:38.523Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}