Troubleshooting guide
Paperless-ngx Import or OCR Fails: Read the Consume Path and Task Log
Category: Document Workflow
paperless ngx ocr not working.
Paperless-ngx problems split into file visibility, task processing, and OCR quality. Test one document so each layer has a clear result.
Before you start
- Paperless-ngx URL and admin/user access
- The host consume path and container mount
- One simple PDF or clear scan
- Access to task/worker logs
Step-by-step checks
Step 1: Verify the consume mount
Compare the host folder with the container's consume path. Create a tiny text PDF in the host folder and confirm it appears inside the container with readable permissions.
Check: The same file is visible at the configured consume path in the container.
Step 2: Watch one task
Upload the sample and follow its task in the UI and worker log. Record the document ID, start time, and first error rather than re-uploading repeatedly.
Check: The task reaches success or gives a specific failure message.
Step 3: Check OCR text
Open the document's text panel and compare a unique phrase from the page. If the text is empty, confirm the OCR language and whether the PDF already contains a text layer.
Check: A unique phrase from the page appears in the text panel.
Step 4: Search and open the original
Search for the unique phrase and open the result. Download the stored original and confirm it matches the source file.
Check: Search returns the document and the original opens correctly.
Step 5: Repeat with one real sample
Once the simple file passes, repeat with one representative real document. Note any difference in scan quality, language, or file size.
Check: The real sample also imports, OCRs, and searches.
Verify the result
The sample has a stored original, readable OCR text, and a search hit. The task log shows no hidden failure after the document appears.
Rollback
Remove only the test document and its test tag after verification. Keep the original scan outside Paperless-ngx.
Ask for help with this exact symptom · All troubleshooting guides