{"record":{"id":"6c9453dce9deb360","repo":"ocrmypdf/OCRmyPDF","slug":"clean-is-required-for-unpaper-args","errorCode":null,"errorMessage":"--clean is required for --unpaper-args","messagePattern":"--clean is required for --unpaper-args","errorType":"validation","errorClass":"BadArgsError","httpStatus":null,"severity":"error","filePath":"src/ocrmypdf/_validation.py","lineNumber":116,"sourceCode":"            # The '\\0' sentinel is only ever set by the CLI, which always\n            # supplies output_file as a plain path - not a stream. If this\n            # somehow fires, the caller mixed a CLI-only sentinel with the\n            # stream-based API.\n            raise BadArgsError(\n                \"--sidecar filename needed when output file is not a path.\"\n            )\n        options.sidecar = os.fspath(options.output_file) + '.txt'\n    if options.sidecar == options.input_file or options.sidecar == options.output_file:\n        raise BadArgsError(\n            \"--sidecar file must be different from the input and output files\"\n        )\n\n\ndef check_options_preprocessing(options: OcrOptions) -> None:\n    if options.clean_final:\n        options.clean = True\n    if options.unpaper_args and not options.clean:\n        raise BadArgsError(\"--clean is required for --unpaper-args\")\n    if (\n        options.rotate_pages_threshold != DEFAULT_ROTATE_PAGES_THRESHOLD\n        and not options.rotate_pages\n    ):\n        raise BadArgsError(\"--rotate-pages is required for --rotate-pages-threshold\")\n    if options.clean:\n        check_external_program(\n            program='unpaper',\n            package='unpaper',\n            version_checker=unpaper.version,\n            need_version='6.1',\n            required_for=\"--clean, --clean-final\",\n        )\n\n\ndef check_options_strip(options: OcrOptions) -> None:\n    \"\"\"Reject options that cannot apply in strip mode.\n","sourceCodeStart":98,"sourceCodeEnd":134,"githubUrl":"https://github.com/ocrmypdf/OCRmyPDF/blob/5074a0b0e109362422b768fd271ed84bf717c4ec/src/ocrmypdf/_validation.py#L98-L134","documentation":"Raised when --unpaper-args is given without --clean. unpaper is only invoked as part of the clean preprocessing step, so its arguments are meaningless without it.","triggerScenarios":"options.unpaper_args set while options.clean is false (note: --clean-final implies clean); checked in check_options_preprocessing.","commonSituations":"Users adding unpaper options expecting unpaper to run independently; forgetting that --clean is the switch that invokes unpaper.","solutions":["Add --clean (or --clean-final, which implies it) to the command","Remove --unpaper-args if cleaning is not wanted"],"exampleFix":"# before\nocrmypdf --unpaper-args '--layout double' in.pdf out.pdf\n# after\nocrmypdf --clean --unpaper-args '--layout double' in.pdf out.pdf","handlingStrategy":"validation","validationCode":"if unpaper_args and not clean:\n    clean = True  # or reject","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Remember --clean gates all unpaper functionality; treat --unpaper-args as a sub-option of --clean"],"tags":["ocr","ocrmypdf","unpaper","cli-arguments"],"backgroundTag":"dependent-option-missing","analyzedSha":"5074a0b0e109362422b768fd271ed84bf717c4ec","analyzedAt":"2026-08-27T11:57:38.523Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}