ocrmypdf/OCRmyPDF · error · BadArgsError

--mode strip removes the OCR text layer without rasterizing

Error message

--mode strip removes the OCR text layer without rasterizing or running OCR, so these options have no effect and are not allowed: {', '.join(used)}

What it means

Raised when --mode strip is combined with options that only matter if OCR or rasterization happens (e.g. --oversample, --remove-vectors, --sidecar, deskew/clean/etc.). Strip mode only deletes the text layer, so those options are rejected as having no effect.

Source

Thrown at src/ocrmypdf/_validation.py:152

    ``--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
    incompatible = {
        '--deskew': options.deskew,
        '--clean': options.clean,
        '--clean-final': options.clean_final,
        '--remove-background': options.remove_background,
        '--rotate-pages': options.rotate_pages,
        '--oversample': options.oversample,
        '--remove-vectors': options.remove_vectors,
        '--sidecar': options.sidecar,
    }
    used = sorted(name for name, value in incompatible.items() if value)
    if used:
        raise BadArgsError(
            "--mode strip removes the OCR text layer without rasterizing or "
            "running OCR, so these options have no effect and are not allowed: "
            f"{', '.join(used)}"
        )


def _check_plugin_invariant_options(options: OcrOptions) -> None:
    check_platform()
    check_options_strip(options)
    check_options_sidecar(options)
    check_options_preprocessing(options)


def _check_plugin_options(
    options: OcrOptions, plugin_manager: OcrmypdfPluginManager
) -> None:
    # First, let plugins check their external dependencies
    plugin_manager.check_options(options=options)

View on GitHub (pinned to 5074a0b0e1)

Solutions

1. Remove the listed options from the command when using --mode strip
2. If you need those options, use a different mode (default/force/redo)

Example fix

# before
ocrmypdf --mode strip --oversample 300 in.pdf out.pdf
# after
ocrmypdf --mode strip in.pdf out.pdf

STRIP_FORBIDDEN = {'oversample','remove_vectors','sidecar','deskew','clean','clean_final'}
if mode == 'strip':
    used = [f for f in STRIP_FORBIDDEN if getattr(opts, f)]
    assert not used, f'strip mode forbids: {used}'

When it happens

Trigger: options.mode == 'strip' and any entry in the incompatible-options dict is truthy; the error lists the offending flag names; checked in check_options_strip.

Common situations: Reusing a long flag-laden command line and swapping the mode to strip without pruning flags.

Related errors

• --redo-ocr (or --mode redo) is not currently compatible with
• 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/a27ac4dbbc67c640. Report an issue: GitHub.