ocrmypdf/OCRmyPDF · error · BadArgsError

--rotate-pages is required for --rotate-pages-threshold

Error message

--rotate-pages is required for --rotate-pages-threshold

What it means

Raised when --rotate-pages-threshold is customized without enabling --rotate-pages. The threshold only tunes the rotation feature, which must be turned on first.

Source

Thrown at src/ocrmypdf/_validation.py:121

                "--sidecar filename needed when output file is not a path."
            )
        options.sidecar = os.fspath(options.output_file) + '.txt'
    if options.sidecar == options.input_file or options.sidecar == options.output_file:
        raise BadArgsError(
            "--sidecar file must be different from the input and output files"
        )


def check_options_preprocessing(options: OcrOptions) -> None:
    if options.clean_final:
        options.clean = True
    if options.unpaper_args and not options.clean:
        raise BadArgsError("--clean is required for --unpaper-args")
    if (
        options.rotate_pages_threshold != DEFAULT_ROTATE_PAGES_THRESHOLD
        and not options.rotate_pages
    ):
        raise BadArgsError("--rotate-pages is required for --rotate-pages-threshold")
    if options.clean:
        check_external_program(
            program='unpaper',
            package='unpaper',
            version_checker=unpaper.version,
            need_version='6.1',
            required_for="--clean, --clean-final",
        )


def check_options_strip(options: OcrOptions) -> None:
    """Reject options that cannot apply in strip mode.

    ``--mode strip`` removes the OCR text layer in place without rasterizing or
    running OCR, so image-processing and OCR-output options have no effect.
    """
    if options.mode != ProcessingMode.strip_text:
        return

View on GitHub (pinned to 5074a0b0e1)

Solutions

1. Add --rotate-pages to the command
2. Remove --rotate-pages-threshold if automatic rotation is not desired

Example fix

# before
ocrmypdf --rotate-pages-threshold 0.6 in.pdf out.pdf
# after
ocrmypdf --rotate-pages --rotate-pages-threshold 0.6 in.pdf out.pdf

if rotate_pages_threshold != default and not rotate_pages:
    rotate_pages = True  # or strip threshold

When it happens

Trigger: options.rotate_pages_threshold != DEFAULT_ROTATE_PAGES_THRESHOLD while options.rotate_pages is false; checked in check_options_preprocessing.

Common situations: Users tuning detection sensitivity without realizing the base flag is required.

Related errors

• --redo-ocr (or --mode redo) is not currently compatible with
• --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
• --mode strip removes the OCR text layer without rasterizing

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