Troubleshooting lessons

Problem: Dokploy says the domain resolves to a private address

Symptom:

mail.example.com resolves to 10.x.x.x

Cause:

hostname: mail.example.com

Docker’s internal DNS associated the public name with the container’s private address.

Fix:

# Remove this line
hostname: mail.example.com

Keep the hostname configured inside Stalwart.

Problem: Port 587 is published but refuses connections

Docker shows:

0.0.0.0:587->587/tcp

but the client receives:

Connection refused

Cause: no Stalwart listener exists on port 587.

Fix:

Settings
→ Network
→ Listeners
→ Add SMTP listener

Use:

Bind: [::]:587
Implicit TLS: Disabled

Problem: Outgoing messages remain in the queue

Error:

Cannot assign requested address
os error 99

Cause: the VPS public IP was added to Stalwart’s source-IP list, but the container does not own that IP.

Fix:

Connection strategy:
EHLO hostname: mail.example.com
Source IPs: empty

Let Docker NAT the connection to the public VPS address.

Problem: IPv6 delivery fails

Error:

Network is unreachable
os error 101

Cause: the VPS has IPv6, but the Stalwart Docker network does not.

Fix:

MX route:
IP lookup strategy = v4Only

Configure IPv6 later only after all of these exist:

• Docker IPv6 networking

• An AAAA record

• IPv6 PTR

• IPv6 SPF authorization

• Correct outbound routing

Problem: Port 25 times out from a home computer

Possible cause: the local internet provider blocks outbound port 25.

Confirm the server using:

• Another VPS

• A real inbound message

• An external SMTP checker

• Stalwart logs showing outside connections

Do not assume a residential port-25 test proves the VPS is blocked.

Problem: “No TLS certificates available”

This may appear before the file-backed certificate is loaded.

The authoritative test is:

openssl s_client \
  -connect mail.example.com:465 \
  -servername mail.example.com

If the correct trusted certificate is presented, SMTP TLS is functioning.

Problem: The RSA DKIM key appears split

Output such as:

"first portion" "second portion"

is normal TXT-record chunking.

It is still one logical DKIM value.