Guides · troubleshooting
Symptom, cause, fix.
Ordered by how often each one actually happens. The first two cover most of it, and both are DNS rather than mxhop.
Start with these three commands
# 1. does mxhop agree with what you think you configured mxhop check # 2. is it well right now mxhop health # 3. what is waiting, and why jq -r '[.id, .attempts, .last_reply] | @tsv' \ /var/lib/mxhop/spool/queue/*.json 2>/dev/null
That third one answers most "mail is not arriving" questions outright. last_reply is the destination's own sentence about why it would not take the message.
Mail arrives, but lands in spam
Check the PTR record first — it is the usual answer
From a machine that is not the server:
dig +short -x 203.0.113.10 mx.example.com. # and the round trip receivers actually check dig +short A mx.example.com 203.0.113.10
Both must agree, and the name must match your hostname exactly. Missing, generic (vps-1234.provider.net), or pointing somewhere else and several large receivers distrust you whatever else is right. Fix it at your IP provider's panel, not in your DNS zone.
Read the real headers rather than guessing
In Gmail: open the message, "Show original". That page tells you precisely which check failed:
spf=pass dkim=pass dmarc=pass arc=pass <- all well spf=fail <- SRS missing, or SPF does not authorise this host dkim=fail <- something altered the bytes before it reached you dmarc=fail<- neither SPF nor DKIM aligned with the From: domain
Each one points at a different fix, and guessing between them wastes a day. See Authentication.
No [srs] block
mxhop check says so in plain words: no SRS — forwarded mail keeps the original envelope sender and will fail SPF. Add the block, and make sure the SRS domain's SPF authorises this host and its MX points here.
A new IP with no sending history
Nothing is wrong. A fresh address has no reputation, and large receivers are cautious with low-volume senders they have not seen. Mark a few as "not spam" in the destination mailbox and it settles over a week or two. Check the IP is not on a blocklist from a previous tenant — that one does not settle on its own.
Nothing arrives at all
Is anything listening, from outside?
openssl s_client -starttls smtp -connect mx.example.com:25 -quiet <<'EOF' EHLO probe.example QUIT EOF 220 mx.example.com mxhop ready
No greeting means it is not reachable, and almost always a firewall or a provider blocking port 25 outbound and inbound on cheap plans. Many providers block 25 by default and will unblock on request; some will not at all.
Does the MX record point here?
dig +short MX example.com 10 mx.example.com.
If you changed it recently, the old value may still be cached for its TTL. A trailing dot matters in zone files; some providers add it for you and some do not.
Is the socket unit stopped?
With socket activation, systemctl status mxhop can look fine while nothing is listening, because the socket unit is the thing that binds the port:
systemctl status mxhop.socket
systemctl enable --now mxhop.socket
The reverse also catches people: stopping only mxhop.service looks like it worked, and systemd starts it again the moment a sender connects.
Is the alias actually there?
mxhop check prints the alias count and the domains. A count lower than you expect means a block is misspelled — [domains."example.com".aliases], with the quotes, is easy to get subtly wrong and produces no error because an empty domain is legal.
Senders say my server refused their mail
550 5.7.1 … fails DMARC and that domain asks for failures to be rejected
Working as intended. That message forged a From: domain which publishes p=reject, and forwarding it would have put the forgery on your reputation. mxhop_auth_refusals_total counts these, and on a public MX it will not be zero.
If a legitimate sender hits this, their own DKIM is broken before it reaches you — their problem to fix, and refusing is the honest answer. To confirm rather than assume, set enforce = "off" briefly and read what the verdicts say.
550 5.7.1 on a domain you thought was configured
mxhop refuses a domain it was not configured for — it is not an open relay. mxhop check lists the domains it will accept. A typo in the domain name, or a config file that is not the one being read: check --config and MXHOP_CONFIG, because the service and your shell can easily disagree.
451 4.7.1 could not finish checking …
An authentication stage ran out of its time budget. Almost always slow DNS. The sender will retry and it usually succeeds; if it is persistent, the host's resolver is the thing to look at — a local caching resolver fixes it. Never treated as a pass, which is why it is a 451 and not a quiet acceptance.
554 5.4.6 this message has already passed through this host
A mail loop. Usually an alias forwarding to an address that resolves back to one of your own domains, or a destination mailbox with a forwarding rule pointing back at you. mxhop check catches loops inside the alias table; this reply catches the ones that go out through someone else and come back.
The queue keeps growing
Read last_reply before anything else
jq -r '.last_reply' /var/lib/mxhop/spool/queue/*.json | sort | uniq -c | sort -rn 47 451 4.7.0 Too many connections from this IP 3 421 4.3.2 Try again later
That is the destination rate-limiting you, and it resolves itself. A single destination dominating the list means the problem is with that one destination, not with mxhop.
Is the runner running?
mxhop_queue_sweeps_total should climb every sweep_seconds. Flat means the runner has stopped and nothing is being retried — restart, and check the logs for what it said on the way down.
Is DNS answering?
mxhop health has a resolver line. Without DNS nothing can be delivered, so everything defers and the queue grows at exactly the rate mail arrives.
Is the disk full?
spool: no in mxhop health. While that is true mxhop refuses incoming mail rather than accepting what it cannot store — correct, but it means senders are being turned away. df -h on the spool filesystem, and remember frozen/ is never pruned automatically.
TLS stopped working
The certificate renewed and nothing told mxhop
The commonest TLS failure by a wide margin. mxhop reads the certificate at startup and on SIGHUP; a renewal that writes new files changes nothing until one of those happens. Senders that require TLS start deferring — quietly, because a deferral is not an error anybody emails you about.
# the fix, once certbot renew --deploy-hook "systemctl reload mxhop" # confirm it took: the fingerprint is logged on reload systemctl reload mxhop && journalctl -u mxhop -n 3 -o cat TLS certificate reloaded; new connections use it certificate=/etc/letsencrypt/live/mx.example.com/fullchain.pem sha256=4f:2a:...
The service cannot read the key
mxhop check opens both files as the user that will run and names that user. A certbot directory readable only by root is the classic case — certbot defaults to 0700 on live/ and archive/. Give the mxhop group read access on both directories; copying the files instead means you have to remember to copy them again every renewal.
An incomplete chain
Use fullchain.pem, not cert.pem. A missing intermediate works in some clients and fails in others, so the symptom is that some senders defer — far harder to spot than everything breaking.
openssl s_client -starttls smtp -connect mx.example.com:25 2>&1 | grep -i verify Verify return code: 0 (ok)
It will not start
| Message | Fix |
|---|---|
| cannot listen: Address already in use | Something else holds port 25 — often Postfix or Exim preinstalled by the distribution. ss -tlnp 'sport = :25', then disable it. |
| cannot listen: Permission denied | Port 25 needs privilege. Use the socket-activated unit, or CAP_NET_BIND_SERVICE, or a high port behind a port mapping. |
| cannot open the spool | The directory does not exist or is not writable by the running user. install -d -o mxhop -g mxhop -m 0750 /var/lib/mxhop/spool. |
| unknown field `…`, expected one of … | A misspelled key. The message lists the keys that block accepts; see the reference. |
| via = "…" has no address | A via host that does not resolve. Fix the name or the internal DNS. check refuses to pass this because the mail would have nowhere to go. |
| the unit fails at ExecStartPre | mxhop check failed, so systemd would not start the service. This is deliberate — a bad config means the previously running process keeps serving. Run mxhop check by hand to see why. |
Still stuck
Collect these four things before opening an issue — they answer most of what anyone would ask you:
mxhop --version
mxhop check
mxhop health
journalctl -u mxhop -n 50 -o cat
Log output is safe to share — no message content, no subjects, no headers beyond the Message-ID. Your config file is not: it names the mailboxes you forward to and the paths to your SRS and ARC keys. Redact the addresses, and never paste the key files themselves.