Troubleshooting guide
Paperless-ngx Watch Folder Not Importing: Diagnose the Consume Directory
Category: Document Workflow
You placed files in the watched import folder, but Paperless-ngx never picks them up, and you are stuck before running a controlled diagnosis.
Confirm the container sees the folder
Open a shell in the Paperless container and list the consume path from your configuration, usually /usr/src/paperless/consume. If your files are absent there, the Docker volume is not mounted where Paperless expects. Check the compose file: the host path must map to that exact container path, and the service must be recreated after changes, not just restarted.
Check permissions and polling
If the files appear in the container but are ignored, compare ownership. The paperless user must be able to read and traverse the directory. Run ls -ln on the folder; a root-owned file with restrictive modes will be skipped. Also confirm PAPERLESS_CONSUMER_POLLING is set if your volume does not deliver filesystem events, since network shares often do not.
Verification test
Create a small text file directly inside the container consume directory, then watch the logs for a consume event. If that file imports but host-placed files do not, the problem is the mount or permissions, not the consumer. This isolates the failure before you change configuration.
Rollback note
Before editing compose mounts or environment variables, save a copy of the working file. If imports still fail, restore it and recreate the container to return to the known state.
When the checks above do not resolve why the paperless ngx watch folder not importing, gather your compose mount lines and container ls output, then
