How to Configure Health Checks for Home Assistant and Its Dependencies

Configure health checks in layers: verify the Home Assistant application response first, then test the database, MQTT, DNS, storage, and remote path only where each dependency actually matters.

A container marked running may still be starting, blocked on storage, disconnected from its broker, or unable to write history. Begin with a cheap local readiness check, add separate dependency checks with clear names, allow enough startup grace, and send alerts before enabling recovery automation. Every probe should say what failed and what a passing result proves.

Define Healthy Behavior Before Writing a Probe

List the functions that must work for your household: the local UI responds, automations execute, Recorder can write, MQTT devices exchange state, DNS resolves required names, and mounted storage is writable. A single green status cannot prove all of those functions.

A practical Docker health-check guide distinguishes application health from simple process existence and explains that a probe runs inside the container and reports success or failure. Use that application-level distinction when defining what your Home Assistant check must observe.

Assign one owner and one failure meaning to every probe. The Core check should not pretend to validate the database, and an MQTT socket check should not claim that device messages are fresh. If a result cannot lead to a specific next action, simplify or remove that probe.

Add a Lightweight Home Assistant Readiness Check

Use a local endpoint or command that completes quickly and proves the application is responding, not merely that the Python process exists. Set a timeout shorter than the interval, a reasonable retry count, and a startup grace period long enough for your measured cold start.

Compose health checks normally expose interval, timeout, retries, and start-period controls, while dependency conditions can delay a consumer until a prerequisite becomes healthy. The key operational behavior is readiness instead of running state, not an aggressive polling schedule.

Start Home Assistant from cold storage and record when the probe first succeeds. If it fails during every normal startup, increase grace rather than weakening the test. If it succeeds before the UI or required service is usable, the check is too shallow and needs a more representative response.

Check Dependencies Separately and Preserve Failure Meaning

Create independent checks for the database connection, MQTT broker, DNS resolution, and required storage mount. Prefer a read-only query or a tiny reversible write to a dedicated test path; never modify Home Assistant tables or publish commands to real devices merely to prove availability.

Keep discovery and local-control dependencies distinct from remote-access dependencies. The ZimaSpace overview of Home Assistant component dependencies provides a useful map for deciding which failure should page you immediately and which can remain a degraded warning.

Label the result with the failing layer. If Home Assistant is healthy but the database check fails, investigate storage or credentials instead of restarting Core. If only remote access fails, keep local control running. This separation prevents one red dependency from erasing evidence in healthy services.

Featured

ZimaCube 2 Personal Cloud Home NAS

ZimaCube2

$799.00 - $2,499.00

Buy Now

Test Failure, Recovery, and Alert Timing

In a maintenance window, stop one noncritical dependency at a time or block its test path temporarily. Confirm the corresponding probe fails, unrelated checks remain green, and the alert names the correct layer. Restore the dependency and verify the same check clears without manual state editing.

Add automatic restarts only after observing several real failures. Use cooldowns and a maximum attempt count, and never restart the database and Home Assistant simultaneously without preserving logs. A restart is a verification gate, not proof that the underlying dependency recovered.

A passing design detects the controlled failure within the expected window, preserves local functions that do not depend on it, and clears after restoration. Roll back probes that create material load or false alarms; escalate if the service remains unready while every dependency check passes, because the application-level test then needs deeper evidence.