Local traffic triggering http.x-forwarded-missing warning

Issues
1

Issue Description

I have stalwart behind a reverse proxy and have it configured with reading x-forwarded-for headers. I noticed I’m getting warnings in the log file that relate to local port 443 (caddy uses 8080) and remoteIp 127.0.0.1 which is localhost, so I’m assuming, there is some internal traffic hitting port 443, which triggers the warning.

Since this occurs every 30s, it leads me to believe this is some periodic check or something?

Expected Behavior

No warnings in the log file.

Actual Behavior

Warning in the log file every 30 seconds

Reproduction Steps

  1. Configure stalwart to obtain client IP from x-forwarded-for headers
  2. Run stalwart (docker)
  3. Observe log output

Relevant Log Output

2026-05-11T07:07:52Z WARN X-Forwarded-For header is missing (http.x-forwarded-missing) listenerId = “https”, localPort = 443, remoteIp = 127.0.0.1, remotePort = 60528

Stalwart Version

v0.16.x

Installation Method

Docker

Database Backend

RocksDB

Blob Storage

RocksDB

Search Engine

Internal

Directory Backend

Internal

I have reviewed the documentation and FAQ and confirm that my issue is NOT addressed there.

on

I have searched this support forum (open and closed topics) and confirm this is not a duplicate.

on

I understand that topics in this category are triaged by a bot first but a human reply will follow up. If I’d prefer a human-only reply, I’ll add the no-ai tag to my topic.

on

2

Let me research this to give you an accurate answer.

The situation is clear. Here’s what’s happening and what you can do about it:

Root cause: Stalwart’s /healthz/live and /healthz/ready endpoints are being polled every ~30 seconds (likely by Docker’s own health check or Caddy’s upstream health checking). These requests come from 127.0.0.1 with no X-Forwarded-For header, so Stalwart correctly fires the http.x-forwarded-missing warning because you have use_forwarded enabled.

This is expected behavior – it’s not a bug, just an internal health-check probe bypassing the reverse proxy. The server still falls back to the real connection IP (127.0.0.1) and handles the request normally.

To silence the warning, you can exclude the http.x-forwarded-missing event from your tracer. In the WebUI, go to Settings › Telemetry › Tracers, edit your tracer, and add http.x-forwarded-missing to the Events list with the policy set to Exclude. The relevant tracer fields are:

  • events: ["http.x-forwarded-missing"]
  • eventsPolicy: "exclude"

This tells the tracer to suppress that specific event type while logging everything else normally.

Relevant docs: Tracer object reference and Telemetry / Tracing

This is an automated reply from the Stalwart Help Bot. Other community members may follow up if this answer is incomplete or wrong. If you found it useful, mention @helpbot in any reply to ask follow-up questions and the bot will respond again.

3

The next Docker images will include X-Forwarded-For headers when accessing the healthz endpoint.

4

The fix is already in the pipeline — the next Docker images will include X-Forwarded-For headers on the /healthz health check requests, so the warning will stop appearing automatically once you update.

In the meantime, the workaround of excluding http.x-forwarded-missing from your tracer (as described above) remains valid if you want to silence the warning before then.

This is an automated reply from the Stalwart Help Bot. Other community members may follow up if this answer is incomplete or wrong. If you found it useful, mention @helpbot in any reply to ask follow-up questions and the bot will respond again.