Container marked unhealthy but service works

Symptom

A container — typically the frontend — shows unhealthy in docker ps, yet the application is reachable and serving normally in the browser. The health probe logs a “connection refused” even though the service is up.

The cause: the probe targets localhost, which resolves to both IPv6 (::1) and IPv4 (127.0.0.1). The probe tool tries IPv6 first, but the server inside the container listens on IPv4 only — so the IPv6 attempt is refused and the probe wrongly reports the container down.

Confirm

Check the container’s reported health versus its real reachability:

docker ps --format '{{.Names}}\t{{.Status}}' | grep aiboard

If a container reads (unhealthy) but the app responds when you hit it directly on IPv4, it is this false negative:

# from inside the container — IPv4 explicitly
docker compose -f docker-compose.release.yml exec frontend \
  sh -c 'wget -qO- http://127.0.0.1:8080/ >/dev/null && echo "IPv4 OK"'

If IPv4 OK prints, the service is healthy and only the probe was wrong.

Fix

Current images already probe IPv4 explicitly, so a healthy box should not hit this. If you do see it on an older image:

1. Confirm the service is actually serving (the IPv4 check above prints IPv4 OK). If it does, no application action is needed — the container is healthy.

2. Update to a current release image, where the health probe targets 127.0.0.1 directly and the false negative is gone:

   docker compose -f docker-compose.release.yml up -d

3. Re-check the status clears:

   docker ps --format '{{.Names}}\t{{.Status}}' | grep aiboard

Caution

Because the probe is what was wrong (not the service), a dependent container waiting on this one’s health can be held back even though everything is actually serving. Fix the probe rather than disabling the healthcheck.

Prevent

• Probe the address the server actually binds. Health probes should target 127.0.0.1 explicitly when the server listens on IPv4 only, so name resolution can’t send the probe to an unbound IPv6 address.
• Distinguish probe failures from service failures. Before reacting to an unhealthy status, confirm with a direct IPv4 request. A green app behind a red probe is a probe bug, not an outage.

Related

• Observability & Alerts — interpreting health and status signals.