Paperless-NGX Troubleshooting – Common Pitfalls and Quick Checks

Paperless-ngx is running but not importing documents? OCR returns empty results or the consume folder remains silent? This article brings together the most common practical pitfalls and provides quick checks for systematically narrowing down typical problems in Docker, NAS and NFS setups – compact, technical and straight to the point.

More Articles About Paperless-ngx

• What Paperless-NGX Really Delivers in Everyday Use
• Installing Paperless-NGX: Requirements, Deployment Models and the Path to a Working Installation
• Paperless-NGX on Synology: NFS Mounts, Clean Drive Integration and a Stable Docker Setup

Paperless Starts, but No Documents Appear in the Inbox

Possible causes:

• incorrect or empty consume path
• directory not mounted correctly
• missing write permissions for the container

Checks:

docker compose logs paperless | grep -i consume
docker exec -it paperless ls -l /usr/src/paperless/consume
Code language: Bash (bash)

➡️ Is the document really present in the container’s consume directory, rather than only on the host?

Documents Are Imported, but OCR Returns No Text

Possible causes:

• OCR languages not configured correctly
• unsupported document types
• very poor scan quality

Checks:

• Check the OCR language:

PAPERLESS_OCR_LANGUAGE: deu+eng
Code language: YAML (yaml)

• Test: upload a PDF with clearly readable text and search specifically for a word.

➡️ Paperless itself may be running correctly, but OCR is only as good as the input data.

Containers Are Running, but the Web UI Is Not Reachable

Possible causes:

• port already in use
• incorrect port mapping
• container is not running reliably

Checks:

docker compose ps
docker compose logs paperless
Code language: Bash (bash)

➡️ Alternatively, try a different port, for example 8080:8000.

PostgreSQL Errors or Paperless Loses Its Database Connection

Possible causes:

• database not yet initialised
• volume damaged or empty
• credentials inconsistent

Checks:

docker compose logs db
docker exec -it paperless-db psql -U paperless -d paperless
Code language: Bash (bash)

➡️ If necessary, stop the containers cleanly and restart them (do not delete volumes immediately).

Paperless Is Running but Responds Slowly or with Delays

Possible causes:

• not enough RAM
• slow storage
• OCR processing too many documents at once

Checks:

docker stats
Code language: Bash (bash)

➡️ On smaller systems such as a NAS or Raspberry Pi, it is advisable to import large batches of documents in stages.

Documents in the Consume Folder Are Processed Only When the Container Starts (NFS)

Symptom:

• Documents are imported only when the container starts.
• New files in the consume folder are not detected automatically.

This behaviour typically occurs when the consume folder is mounted via NFS.

Cause: Paperless-NGX uses Inotify by default to detect filesystem events.
With NFS mounts, however, these events are not reliably passed to the container, or not passed at all.

This is not a Paperless error, but a technical limitation of NFS in combination with Inotify.

Solution: Enable Polling for the Consume Folder

In this case, polling should be enabled.
Paperless then actively checks at regular intervals whether new files are present in the consume folder.

Setting in docker-compose.yml

environment:
  PAPERLESS_CONSUMER_POLLING: "5"
Code language: YAML (yaml)

The value specifies the interval in seconds at which Paperless checks the consume folder.

Proven values in practice:

• 5 seconds → very reliable, minimal overhead
• 10–30 seconds → sufficient for most setups

When Is Polling Useful?

Polling should be enabled when:

• the consume folder is mounted via NFS
• external systems (scanners, Drive, sync tools) place files there
• importing works only when the container starts

Polling is not a workaround; it is the recommended operating mode for NFS-based consume directories.

When Is Polling Not Necessary?

Polling is usually not required when:

• the consume folder is mounted locally
• no network filesystems are involved
• Inotify reliably delivers events

Conclusion on NFS & Consume Processing

When Paperless-NGX uses NFS, you should not expect Inotify – the event-based mechanism for immediately importing documents from the scan folder – to work reliably. Enabling polling provides:

• deterministic behaviour
• stable imports
• traceable processing

Especially in combination with NAS systems, polling is the more robust and less troublesome solution.

Documents Are Imported Multiple Times

Possible causes:

• documents remain in the consume directory
• scanner copies files instead of moving them
• an external sync process accesses them in parallel

Checks:

• check the consume directory after import
• configure the scanner to “Move” rather than “Copy” files

➡️ The consume folder should be used as a pure inbox, not as storage.

Users Can Log In but Cannot See Any Documents

Possible causes:

• permissions/role concept not configured correctly
• documents are assigned to other users

Checks:

• review user roles in the settings
• temporarily grant administrator permissions for testing

➡️ Paperless is fully multi-user capable – visibility can deliberately be controlled.

When Is a Complete Rebuild Worthwhile?

A complete rebuild is usually not necessary if:

• containers start cleanly
• logs show understandable errors
• data directories are intact

A rebuild is more appropriate in cases of:

• faulty volumes
• multiple experimental configuration changes
• fundamental architectural changes

More Articles About Paperless-ngx

• What Paperless-NGX Really Delivers in Everyday Use
• Installing Paperless-NGX: Requirements, Deployment Models and the Path to a Working Installation
• Paperless-NGX on Synology: NFS Mounts, Clean Drive Integration and a Stable Docker Setup