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


Back to the service page · Ask about this exact symptom