🐳 Docker: Fix a Healthcheck Marking a Container Unhealthy Too Soon
A Docker HEALTHCHECK runs on a fixed interval starting from the moment the container starts, and every failed probe counts toward the unhealthy threshold unless a start period is configured. An application that genuinely needs real startup time — warming a cache, running migrations, waiting on a dependency — will fail every probe during that window, and without a start period those early, expected failures count exactly the same as a probe failing after the app should have been ready.
🔎 The Problem
HEALTHCHECK --interval=5s --timeout=3s --retries=3 \ CMD curl -f http://localhost:8080/ready || exit 1 # App takes ~20s to finish startup work. # No --start-period set -> default is 0s. # 3 failed probes x 5s interval = unhealthy at 15s, before the app is ready.
✅ Fix: Give Startup Its Own Grace Period
- Set
--health-start-period(orstart_periodin Compose) to comfortably cover real startup time, not just the happy-path average — a cold cache or a slow dependency can both push this out. - Point the health check at an endpoint that only returns success once the app is actually serving real traffic, not one that returns 200 the instant the process is alive but before it’s finished initializing.
- Watch
docker inspect‘s health status log during a realistic startup to confirm failures stop landing once the start period is in effect, instead of just assuming the new value is long enough.
🚨 Why This Is Dangerous
- An orchestrator that restarts a container the moment it’s marked unhealthy can get stuck in a restart loop where the app never survives long enough to finish its own startup work, each restart resetting the clock right back to zero.
A health check that can’t tell ‘still starting’ from ‘actually broken’ will eventually punish an app for the one thing every app has to do once: start up.
