Troubleshooting guide
Paperless-ngx Import Folder Not Detected: Diagnose the Watched Volume
Category: Document Workflow
You placed files in the Docker watched folder, but Paperless-ngx never picks them up, and you are stuck before running a controlled diagnosis.
Confirm the container sees the folder
Run docker exec -it <container> ls -la /usr/src/paperless/consume. If the command returns an error or an empty directory while files exist on the host, the volume mount is wrong. Check your compose file for the consume volume line and confirm the host path matches the folder you are actually using. A correct result lists your files with the paperless user as owner.
Check the consumer process
Run docker logs <container> 2>&1 | grep -i consume. You want a line showing the consumer started and watching the directory. If the log shows a permission error or no consumer line at all, the service is not watching. Also confirm PAPERLESS_CONSUMER_POLLING is set if your volume does not emit filesystem events; without it, files can sit indefinitely.
Verify permissions
The container user must read and write the consume folder. Run docker exec -it <container> id and compare the UID/GID with ls -n on the host folder. If they differ, adjust ownership with chown -R <uid>:<gid> <host-path>. This is the most common reason a paperless ngx import folder not detected issue persists after the mount looks correct.
Verification test
Create a small text file directly inside the host folder, wait up to one minute, then check docker logs <container> --tail 50. A successful consume logs the file being processed and it appears in the documents list. If nothing appears, the mount or consumer is still wrong.
Rollback note
If a compose or permission change breaks startup, restore your previous compose file and restart the container before retrying. Keep a copy of the working configuration.
If these checks do not resolve it,
