Troubleshooting guide
Paperless-ngx Consumer Service Restart: When a File Stays in the Consume Queue
Category: Document Workflow
You uploaded a file to your watched import volume, but it is still sitting in the consume queue and never becomes a searchable document.
Check the Consumer Container Status
Run docker ps and look for the consumer container. If it is not listed or shows Exited, the consumer is not running. Check its logs with docker logs <consumer_container_name> --tail 50. Look for errors like Permission denied, No such file or directory, or repeated tracebacks. If the logs show a clean startup but no processing activity, the consumer may be idle or stuck on a lock. Note the exact error message; that tells you whether this is a permissions issue, a missing volume, or a crashed process.
Confirm the Queue and Volume
Inspect the consume directory inside the container: docker exec <consumer_container_name> ls -la /usr/src/paperless/consume. If your file is present but not moving, the consumer is not picking it up. Also check that the host path is correctly mounted by comparing docker inspect <consumer_container_name> | grep -A5 Mounts with your compose file. A mismatch here means the consumer sees an empty folder.
Restart the Consumer
If the logs show a crash or the container is stopped, perform a paperless ngx consumer service restart with docker restart <consumer_container_name>. Wait 30 seconds, then check the logs again for processing messages.
Verification Test
Place a small text file in the consume volume. Within one minute, it should disappear from the queue and appear in the documents list. If it does not, the restart did not resolve the underlying issue.
Rollback and Recovery
If the restart causes repeated crashes, stop the container and review the last error. Revert any recent compose changes before retrying. For persistent queue stalls,

Ask for help with your logs and compose file.