Docs / Help

Troubleshooting

Exit codes (CLI) / exception types (library)

Exit code	Meaning	Likely cause	Library exception
1	User error	File not found, invalid `--format`, blank page without `--force`	`InputFileError`, `OutputPathError`, `ValidationError`, `BlankPageDetectedError`
2	Environment error	Tesseract missing/misconfigured, poppler missing for PDF input	`TesseractEnvironmentError`, `DependencyError`
3	Unexpected error	A bug; rerun with `--verbose` for the stack trace	any unhandled exception
4	Processing error	OCR or PDF stage failed operationally (e.g. a timeout)	`PipelineError` (or subclass)
5	Partial batch failure	Multiple inputs, at least one failed	n/a, check `BatchResult.failures`

Catching these before a batch runs scanlayer *.jpg -o ./converted/ --dry-run checks every input file, Tesseract, and output path up front and exits with the same codes above, without spending time on OCR first. See CLI Reference.

"Blank page" error on a page that has content

The blank-page check looks at grayscale standard deviation (DESKEW_MIN_STD, default 5.0), not OCR confidence, so a very light scan or a mostly-white page can trip it.

bash

scanlayer light-scan.jpg -o out.pdf --force

Or lower the threshold globally if this happens often on your documents:

python

scanlayer.configure(deskew_min_std=2.0)

See Configuration.

Tesseract not found

Set TESSERACT_CMD (env var or scanlayer.configure(tesseract_cmd=...)). See Installation for the full resolution order.

.pdf input fails with a dependency error

Install poppler-utils. pip install pdf2image alone is not enough; poppler is a separate system package. See Installation.

Two-column page reads out of order in the PDF text layer or export

Multi-column detection may not have triggered: it needs at least 6 text lines and a wide, consistent gutter (COLUMN_MIN_LINES_FOR_DETECTION, COLUMN_MIN_GUTTER_FRACTION in Configuration), or the layout is table-like rather than prose, which this feature does not target.

A word I expect is missing from the output

Run with --debug-image. If the word is not drawn at all, it was detected and dropped below --min-confidence. See Debug Visualization.

Wrong orientation in the output

Check the --debug-image header band for what correction was actually applied, then override with --orientation none or an exact angle if auto-detection is wrong for this document type. See examples.

Still stuck? Run with --verbose for full logging, and check Roadmap & Limitations in case the behavior you are seeing is a known, deliberate scope boundary rather than a bug.