ocrmypdf/OCRmyPDF · error · ValueError

--redo-ocr (or --mode redo) is not currently compatible with

Error message

--redo-ocr (or --mode redo) is not currently compatible with --deskew, --clean-final, and --remove-background

What it means

Raised when --redo-ocr/--mode redo is combined with --deskew, --clean-final, or --remove-background. These preprocessing options rasterize pages, which conflicts with redo mode's goal of identifying and re-OCRing only existing text without destroying vector content.

Source

Thrown at src/ocrmypdf/_options.py:465

    def validate_redo_ocr_options(self):
        """Validate options compatible with redo mode."""
        if self.mode == ProcessingMode.redo and (
            self.deskew or self.clean_final or self.remove_background
        ):
            raise ValueError(
                "--redo-ocr (or --mode redo) is not currently compatible with "
                "--deskew, --clean-final, and --remove-background"
            )
        return self

    @model_validator(mode='after')
    def validate_output_type_compatibility(self):
        """Validate output type is compatible with output file."""
        if self.output_type == 'none' and str(self.output_file) not in (
            os.devnull,
            '-',
        ):
            raise ValueError(
                "Since you specified `--output-type none`, the output file "
                f"{str(self.output_file)} cannot be produced. Set the output file to "
                f"`-` to suppress this message."
            )
        return self

    @property
    def lossless_reconstruction(self):
        """Determine lossless_reconstruction based on other options."""
        lossless = not any(
            [
                self.deskew,
                self.clean_final,
                self.mode == ProcessingMode.force,
                self.remove_background,
            ]
        )
        return lossless

View on GitHub (pinned to 5074a0b0e1)

Solutions

1. Drop --deskew/--clean-final/--remove-background when using --redo-ocr
2. Switch to --force-ocr if rasterizing preprocessing is more important than preserving the original page content
3. Run two passes: first --mode redo, then a separate pass with preprocessing on the output

Example fix

# before
ocrmypdf --redo-ocr --deskew in.pdf out.pdf
# after
ocrmypdf --redo-ocr in.pdf out.pdf

redo_conflicts = ['deskew','clean_final','remove_background']
if opts.mode == 'redo' and any(getattr(opts, f) for f in redo_conflicts):
    raise SystemExit('redo mode forbids deskew/clean-final/remove-background')

When it happens

Trigger: Passing both --redo-ocr (or --mode redo) and any of --deskew, --clean-final, or --remove-background on the CLI or via OcrOptions; validated during options checking before processing starts.

Common situations: Users upgrading scripts that combined cleanup flags with redo mode; copying flag sets from older ocrmypdf versions or forum examples.

Related errors

• --mode strip removes the OCR text layer without rasterizing
• This PDF has a user fillable form. --redo-ocr (or --mode red
• --sidecar filename needed when output file is stdout.
• --sidecar filename needed when output file is /dev/null or N
• --clean is required for --unpaper-args

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