Postfix Guide

Postfix Troubleshooting

Resolve common startup, permission and delivery errors.

Overview

Resolve common startup, permission and delivery errors. The safest approach is to make one change at a time, validate syntax, reload the service, and then review logs and delivery results.

Configuration example

# /etc/postfix/main.cf
transport_maps = hash:/etc/postfix/transport

# Validate and reload
postfix check
postmap /etc/postfix/transport
systemctl reload postfix

Recommended procedure

1. Document the current working configuration and relevant IP, DNS and authentication values.
2. Confirm that every referenced file, key, hostname and source IP exists.
3. Apply the smallest possible change and run the service configuration validator.
4. Reload rather than restart when the software supports safe reloads.
5. Watch logs, queue growth, SMTP responses and provider-specific behavior.

Common mistakes

• Copying a configuration from a different software release without checking directive support.
• Using a source IP without matching PTR, forward DNS and HELO identity.
• Changing multiple routing and throttling rules at once, making failures difficult to isolate.
• Ignoring envelope sender behavior, bounce handling and complaint suppression.

Verification

systemctl status postfix || systemctl status pmta
ss -lntp
tail -f /var/log/maillog
# Send a controlled test and inspect the complete received headers.

Production notes

Delivery settings should be based on current response data, list quality and reputation. A value that works for one server or ISP can be unsafe for another. Prefer conservative defaults and measured increases.

Related Postfix guides