home-assistant-troubleshooting

Troubleshooting Home Assistant

This work is read-only and ends in a recommendation. Gather evidence, explain what it shows, propose the smallest fix — and stop. Do not edit files, call services, restart, reload, or "just try" a change while investigating. The user asks for a fix separately, and then the configuration skill applies.

Keep queries bounded

Diagnostics is where context gets burned. Every query below has a narrower form; use it. A dump of every entity or a full log crowds out the evidence that actually matters.

• get_home_context before any broad listing — it answers most "what exists" questions in a fraction of the tokens.
• search_entities with a pattern, not get_states with no filter.
• get_states(domain=...) when you do need a list.
• get_history / get_logbook over the shortest window that could show the problem. Start at a few hours, widen only if it is not there. Supplied timestamps must carry Z or a UTC offset.
• get_error_log before get_support_logs; the error log is already filtered.
• get_support_logs when you need Core, Supervisor, host or add-on logs — it is bounded and credential-redacted. Name the component and keep the line count small.

If a query comes back empty, that means that query found nothing. Widen the window or change the search term before concluding the thing does not exist.

Order of attack

Start with diagnose_entity whenever the report names an entity. It bundles current state, recent history, related entities and the common causes, so it usually replaces four separate calls.

Then, depending on what it shows:

Symptom	Next evidence
unavailable / unknown	get_entity_details for the integration and device; get_devices for the parent device; the integration's entries in get_error_log
Entity missing entirely	search_entities for the old and new names; check whether it was renamed or the integration failed to load
Automation did not fire	get_logbook for the automation entity; read the automation YAML; check each condition against get_history at the trigger time
Template error	render_template with the exact expression; check the referenced entities exist and are not unknown
Value looks wrong	get_history for the entity, then for its source entity
Integration failing to set up	get_error_log; get_supervisor_resolution for known issues
Slow, restarting, or out of space	get_supervisor_health, get_supervisor_metrics, get_backup_posture, get_store_audit
Something changed after an update	get_breaking_changes; the release notes for the installed version