Troubleshooting guide
Paperless-ngx Email Import Failed: When the Mail Rule Runs but Messages Never Arrive
Category: Document Workflow
You set up a mail rule in Paperless-ngx, the rule appears to run, yet messages and attachments never reach the inbox, leaving you with a paperless ngx email import failed condition.
Confirm the rule is actually matching messages
Open the mail rule and check the filter fields: folder, subject, from, and attachment type. A rule that runs but matches nothing fails silently. Set the folder to INBOX and temporarily clear subject and sender filters, then save. If the rule still does not fire, the problem is matching, not delivery.
Check the mail account connection
In the same rule, verify the host, port, username, and password. For IMAP use port 993 with SSL; for STARTTLS use 143. A wrong port or an expired app password causes a connection failure that the UI may not surface. Save the rule and watch the container log for authentication or timeout errors.
Inspect the consume path inside Docker
Because you use a watched import volume, confirm the mail rule’s consumption folder maps to a path the container can write. Run docker exec -it <container> ls -la /usr/src/paperless/consume and check ownership. If the folder is missing or not writable by the paperless user, attachments are fetched but discarded. Fix permissions with chown -R 1000:1000 on the host volume, then restart the container.
Verification test
Send a test email with a single PDF attachment to the monitored address. Within one polling cycle, run docker logs --tail 50 <container> and look for a consume task referencing the attachment filename. Then check Documents for the new file. Success means the log shows the task and the document appears; failure means the log shows a connection or permission error you can now target.
Rollback note
If clearing filters or changing ports breaks other rules, restore the previous rule settings from your configuration backup before continuing. If the cause remains unclear,

Ask for help with the relevant log lines.