ocrmypdf/OCRmyPDF · error · PriorOcrFoundError

page already has text! - aborting (use --force-ocr or --mode

Error message

page already has text! - aborting (use --force-ocr or --mode force to force OCR; see also help for --skip-text, --redo-ocr, and --mode)

What it means

Raised in default mode when a page already contains text, because OCRing over existing text produces degraded output. ocrmypdf refuses unless you explicitly choose a strategy (--force-ocr, --skip-text, or --redo-ocr).

Source

Thrown at src/ocrmypdf/_pipeline.py:354

def is_ocr_required(page_context: PageContext) -> bool:
    """Check if the page needs to be OCR'd."""
    pageinfo = page_context.pageinfo
    options = page_context.options

    if options.mode == ProcessingMode.strip_text:
        # Strip mode removes the OCR text layer in place; it never rasterizes
        # or runs OCR. The stripping happens in OcrGrafter.graft_page.
        return False

    ocr_required = True

    if options.pages and pageinfo.pageno not in options.pages:
        log.debug(f"skipped {pageinfo.pageno} as requested by --pages {options.pages}")
        ocr_required = False
    elif pageinfo.has_text:
        if options.mode == ProcessingMode.default:
            raise PriorOcrFoundError(
                "page already has text! - aborting (use --force-ocr or --mode force "
                "to force OCR; see also help for --skip-text, --redo-ocr, and --mode)"
            )
        elif options.mode == ProcessingMode.force:
            log.info("page already has text! - rasterizing text and running OCR anyway")
            ocr_required = True
        elif options.mode == ProcessingMode.redo:
            if pageinfo.has_corrupt_text:
                log.warning(
                    "some text on this page cannot be mapped to characters: "
                    "consider using --force-ocr (or --mode force) instead"
                )
            else:
                log.info("redoing OCR")
            ocr_required = True
        elif options.mode == ProcessingMode.skip:
            log.info("skipping all processing on this page")
            ocr_required = False

View on GitHub (pinned to 5074a0b0e1)

Solutions

1. Use --redo-ocr if the existing text is an OCR layer you want replaced
2. Use --skip-text if you want text pages left alone
3. Use --force-ocr if you must rasterize and re-OCR everything (acknowledging quality loss)
4. Check the input: you may be processing the wrong (already-text) file

Example fix

# before
ocrmypdf scanned.pdf out.pdf  # Error: page already has text!
# after
ocrmypdf --redo-ocr scanned.pdf out.pdf

import pikepdf
with pikepdf.open(src) as pdf:
    has_text = any(page.extract_text() for page in pdf.pages())
if has_text and mode is None:
    mode = 'redo' if from_ocr else 'skip'

catch ocrmypdf.PriorOcrFoundError and re-run with an explicit --mode chosen by the user

When it happens

Trigger: options.mode == ProcessingMode.default (no mode flag) and pageinfo.has_text is true for any page; raised per-page in is_ocr_required.

Common situations: Running ocrmypdf on a digitally-born or previously OCRed PDF without any mode flag.

Related errors

• --redo-ocr (or --mode redo) is not currently compatible with
• Since you specified `--output-type none`, the output file {s
• Input file is an image, but the resolution (DPI) is not cred
• Input file is an image, but has no resolution (DPI) in its m
• The input image has an alpha channel. Remove the alpha chann

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