What “running” means to Docker by default

Without a health check defined, Docker’s only signal for a container’s wellbeing is whether its main process has exited. As long as that process is technically alive, Docker reports the container as running, regardless of whether the application inside is actually functioning correctly.

What HEALTHCHECK adds

HEALTHCHECK is a Dockerfile instruction that defines a command Docker should run periodically, from inside the container, to test whether the application is truly working — not just alive. Based on whether that command succeeds or fails, Docker assigns the container an explicit health status that tools, humans, and orchestrators can all check directly.

Why this distinction matters in practice

A load balancer or orchestrator making decisions about where to send traffic needs to know more than “the container exists.” It needs to know whether sending a request to that particular container right now is likely to succeed. A meaningful health check turns an opaque, always-optimistic “running” status into an honest, continuously updated answer to that exact question.

Together, these pieces let a single instruction express a fairly nuanced policy: what to test, how often to test it, how much patience to have with a single slow response, how many failures in a row actually mean something is wrong, and how long to hold off judgment while the application is still warming up.

Once the container starts, Docker places it into the starting status and begins running the check command on the configured interval. Each run of that command produces an exit code, exactly the way any shell command does: an exit code of zero means the check passed, and any non-zero exit code means it failed. Docker does not interpret the check command’s actual output or logic — it only pays attention to whether the command succeeded or failed as a process.

How the status transitions happen

While inside the start period, failed checks are recorded but do not immediately push the container toward unhealthy — this window exists specifically so a normal, expected startup delay is not mistaken for a real problem. Once the start period ends, or as soon as a check succeeds, Docker begins counting consecutive failures against the configured retry limit. If that many checks in a row fail, the container’s status flips to unhealthy. A single subsequent success is enough to flip it back to healthy immediately — recovery is not held to the same “several in a row” standard as failure.

What Docker does with an unhealthy status by itself

By default, Docker does not automatically restart or stop a container just because it becomes unhealthy — the status is reported, not acted on, unless something else is watching for it. This is an important nuance: the value of a health check often comes from what other systems (an orchestrator, a load balancer, a monitoring alert) do in response to that status, not from Docker itself taking action.

flowchart TD
    A["Container starts"] --> B["Status: starting"]
    B --> C["Check command runs on interval"]
    C --> D{"Check result?"}
    D -->|"Pass, within start period"| B
    D -->|"Pass, start period over"| E["Status: healthy"]
    D -->|"Fail, within start period"| B
    D -->|"Fail, start period over"| F["Failure counted toward retries"]
    F --> G{"Failures reached retries limit?"}
    G -->|"No"| C
    G -->|"Yes"| H["Status: unhealthy"]
    H --> C
    E --> C
    C -->|"Later: check passes again"| E
    

Notice that the loop never actually stops on its own — checks keep running for as long as the container runs, continuously re-evaluating status rather than making a single one-time judgment at startup. This is what makes health checks useful for catching problems that appear well after a container first came up, such as a database connection that was fine at launch but later dropped.

The trade-off in one sentence: a well-designed health check buys genuine visibility into application correctness at the cost of a small, ongoing overhead and the responsibility to design a check that is actually representative of real health.

A check command that queries a database, calls an internal API, or inspects application internals to determine health needs to be written carefully so it never logs or exposes sensitive details — credentials, internal tokens, raw query results — as part of its output or exit behavior, especially if that output ends up in logs collected by a broader monitoring system. It is also worth remembering that the check runs with whatever privileges the container process already has, so a check script is not a safe place to introduce elevated permissions or new network access the rest of the application does not already need.

A reasonable approach keeps the health check itself lightweight and narrowly scoped, avoids putting anything sensitive in its output, and treats the health endpoint (if it is a network endpoint) with the same access considerations as any other part of the application’s surface — even though its purpose is purely operational rather than user-facing.