Paperless-ngx: Consumption Folder Not Processing — Fix

The Problem

Documents dropped into the Paperless-ngx consumption folder aren’t being picked up. Files sit in the directory indefinitely — no OCR, no classification, no import. The web UI shows no new documents.

The Cause

Paperless-ngx watches the consumption directory for new files using inotify (filesystem events) or polling. Several issues can break this: incorrect directory permissions, inotify limits reached on the host, wrong volume mount paths, or the consumer process not running.

The Fix

Method 1: Fix Directory Permissions (Most Common)

The Paperless-ngx container runs as user paperless (UID 1000 by default). The consumption directory must be writable by this user.

# Check current permissions
ls -la /path/to/consumption/

# Fix ownership to match container user
sudo chown -R 1000:1000 /path/to/consumption/
sudo chmod 755 /path/to/consumption/

If you’re using custom UIDs via USERMAP_UID and USERMAP_GID:

# Replace with your actual values from docker-compose
sudo chown -R <USERMAP_UID>:<USERMAP_GID> /path/to/consumption/

Method 2: Verify Volume Mount Path

The consumption folder must be mounted into the container at the correct path. Check your docker-compose.yml:

services:
  paperless:
    volumes:
      - /path/on/host/consume:/usr/src/paperless/consume

Common mistakes:

• Mounting to the wrong container path (must be /usr/src/paperless/consume)
• Using a relative host path that resolves to the wrong directory
• Typo in the path

Verify the mount is working:

# Place a test file
touch /path/on/host/consume/test.txt

# Check it appears inside the container
docker exec paperless ls -la /usr/src/paperless/consume/

Method 3: Increase inotify Watch Limits

Linux limits the number of filesystem watches per user. If you run many containers or services, you may exhaust the limit.

# Check current limit
cat /proc/sys/fs/inotify/max_user_watches

# If it's low (e.g., 8192), increase it
echo "fs.inotify.max_user_watches=524288" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Then restart Paperless-ngx:

docker compose restart paperless

Method 4: Switch to Polling Mode

If inotify doesn’t work reliably (common with NFS, CIFS, or remote mounts), switch to polling:

services:
  paperless:
    environment:
      PAPERLESS_CONSUMER_POLLING: "60"  # Check every 60 seconds
      PAPERLESS_CONSUMER_POLLING_DELAY: "5"  # Wait 5 seconds for file to finish writing

Polling is slower but works with any filesystem type, including network mounts.

Method 5: Check the Consumer Process

Verify the consumer is actually running inside the container:

# Check Paperless-ngx logs for consumer activity
docker compose logs paperless | grep -i "consumer"

# Look for errors
docker compose logs paperless | grep -i "error"

If you see Consumer started, the process is running. If not, the container may have crashed or the consumer failed to start.

Restart the container:

docker compose restart paperless

Method 6: Subdirectory Configuration

If you’re using subdirectories within the consumption folder and they’re not being processed:

environment:
  PAPERLESS_CONSUMER_RECURSIVE: "true"  # Process subdirectories
  PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS: "true"  # Optional: use folder names as tags

Without PAPERLESS_CONSUMER_RECURSIVE, only files directly in the consumption root are processed.

Prevention

• Always verify permissions after Docker updates — image updates may change the internal user ID
• Use polling mode for network mounts — inotify doesn’t work over NFS/CIFS/SMB
• Set PAPERLESS_CONSUMER_POLLING_DELAY to at least 5 seconds to avoid processing partially-written files
• Monitor logs — add PAPERLESS_LOGGING_DIR: "/usr/src/paperless/data/log" to capture detailed logs
• Test after changes — drop a small PDF into the folder and watch the logs:

docker compose logs -f paperless

Related

• How to Self-Host Paperless-ngx
• Paperless-ngx: OCR Not Working — Fix
• Best Self-Hosted Document Management
• Paperless-ngx vs Teedy
• Docker Compose Basics