Troubleshooting guide

Paperless-ngx Consumer Service Restart: Clear a Stuck Consume Queue Safely

Category: Document Workflow

Your watched import volume accepted a file, but it still sits in the consume queue and never appears as a searchable document.

Confirm the Queue Is Actually Stalled

First, check the Paperless-ngx dashboard or the consume queue view. A file that has been waiting for more than a few minutes with no progress is stalled. Next, inspect the consumer container logs for repeated errors, such as permission denied, unsupported file type, or a database lock. If the logs show a clear error, fix that cause first; a restart will not resolve a permissions or format problem.

Perform a Controlled Restart

If the logs show no clear error and the queue is idle, restart only the consumer service rather than the whole stack. Use your Docker Compose service name for the consumer, for example: docker compose restart webserver. This is the paperless ngx consumer service restart step. Wait for the container to report healthy, then return to the queue view. A healthy restart should begin processing the waiting file within a minute or two.

Verification Test

After the restart, watch the queue. The file should leave the queue and appear in Documents with searchable text. Open the document and search for a word you know is inside it. If the file remains queued, stop and collect the consumer logs before trying anything else.

Rollback and Recovery

If the restart does not clear the queue, do not delete the original file. Move it out of the watched volume, confirm the queue is empty, then place a copy back to retry. Keep the original until the document is searchable. If the queue still stalls,

A scanned document and Paperless-ngx search result on a laptop

Ask for help with your logs and compose configuration.


Back to the service page · Ask about this exact symptom