4.2.13.3 HEALTHCHECK Timeout

The HEALTHCHECK timeout setting defines the maximum amount of time Docker waits for a single health check command to complete before considering that particular check attempt a failure, regardless of whether the command would have eventually succeeded given more time.

Setting the Timeout

The --timeout option specifies how long a single invocation of the health check command is allowed to run before being forcibly treated as failed.

HEALTHCHECK --timeout=5s CMD curl -f http://localhost:8080/health || exit 1

If this health check takes longer than 5 seconds to complete, Docker treats that particular attempt as a failure, independent of what the command would have eventually returned.

Why a Timeout Is Necessary

Without a timeout, a health check command that hangs — due to a network issue, a deadlock, or an unresponsive dependency — could block indefinitely, providing no useful signal at all, since the lack of a response is itself meaningful information about the application's health.

HEALTHCHECK --timeout=3s CMD curl --max-time 2 -f http://localhost:8080/health || exit 1

Combining Docker's own timeout with the underlying tool's own timeout option provides a clear, fast failure signal if the health endpoint becomes unresponsive.

Choosing an Appropriate Timeout Value

The timeout should be generous enough to accommodate normal response times under typical load, while still being short enough that a genuinely unresponsive application is detected promptly rather than appearing to hang indefinitely.

HEALTHCHECK --interval=30s --timeout=10s CMD curl -f http://localhost:8080/health || exit 1

Distinguishing Timeout From Interval

The timeout governs how long a single check attempt is allowed to run; the interval governs how often a new check attempt begins — these are independent settings addressing different aspects of the health check's overall behavior.

docker inspect myapp --format '{{json .Config.Healthcheck}}'

This reveals both configured values directly, useful for confirming they are set as intended.

Why the Timeout Setting Matters

An appropriately configured timeout ensures that a health check failure caused by genuine unresponsiveness is detected and reported promptly, rather than the health check itself becoming an indefinitely hanging operation that provides no useful signal about the application's actual state.