Logs, System Health, and Repairs: Where to Look for a Cause Before You Ask the Forum
Logs, System Health, and Repairs: Where to Look for a Cause Before You Ask the Forum
Something isn't working, and you don't know where to start diagnosing it: Home Assistant has three built-in tools that answer exactly this question, before you even open a browser to look for help on the forum. This lesson covers System Health, the Repairs page, the System Log, and per-integration debug logging.
Budget around 50 minutes. These tools come back in every other lesson of this course when diagnosing a specific problem: this lesson gathers them into one general reference.
System Health: The First Stop for Any Problem
System Health, available under Settings, System, Repairs, in the three-dot menu in the top right as System information, shows a consolidated view of your install: system architecture, operating system version, Home Assistant install type and version, Python version, frontend version, the number of dashboards and views, and health information reported by individual integrations.
Repairs: Reported Problems That Need Your Action
System Repairs (introduced in Home Assistant 2022.8) is a list of active problems automatically detected by the system that need your intervention: a misconfigured integration, an outdated way of defining an entity, an integration needing reauthorization. This is the first place to check after every update, covered in this module's Lesson 3.
The System Log and Debug Logging: When Repairs Shows Nothing
If a problem doesn't show up as an active repair, the next step is the System Log, showing error and warning messages generated by Home Assistant and individual integrations in real time. For trickier problems it's worth turning on debug logging for a specific integration: under Settings, Devices and services, select the integration, and enable detailed logging, which generates far more precise information about what's happening under the hood.
An important change in versions 2025.11 and 2026.01
Version 2025.11 removed the home-assistant.log file for HAOS and Supervised users, but as of version 2026.01 you can turn it back on through the Home Assistant CLI. If you're looking for this file and can't find it, check your exact version and use the CLI instead of direct file access.
How to File a Bug Report That Actually Helps
If, after going through System Health, Repairs, the System Log, and debug logging, you still haven't solved the problem, the next step is reporting it: either on the Home Assistant community forum, or as a GitHub Issue for the specific integration. A good report includes the Home Assistant version, the install type, a log excerpt with debug logging enabled, and an exact description of the steps leading to the problem. A report missing this information rarely gets a fast response.
Integration Diagnostics: An Export Ready for a Bug Report
Many integrations in Home Assistant offer a Download Diagnostics option, available under Settings, Devices and services, on a specific integration, in the three-dot menu. The exported file contains organized information about the integration's configuration and state, with sensitive data like passwords or tokens automatically masked, ready to attach to a bug report without manually digging through logs.
Logger: Precise Log-Level Control Per Component
logger:
default: warning
logs:
homeassistant.components.zha: debug
homeassistant.components.recorder: info
custom_components.my_integration: debugThe logger configuration in configuration.yaml lets you set the log level precisely for each component separately, instead of turning on debug logging globally, which would flood the System Log with thousands of unnecessary entries. The default warning level only shows meaningful warnings, while debug for a specific integration (Zigbee from Module 9, for example) gives full visibility into device communication.
Repairs Versus Ordinary Warnings: Telling Priorities Apart
Not every entry in Repairs needs an immediate reaction: the system distinguishes reports of different severity, from informational (an integration will be removed in a future version, say) to critical (an integration has stopped working and needs reauthorization). A practical rule: check reports about lost functionality (red, critical) right away, and you can leave informational notices about upcoming changes for the next monthly review from Lesson 10, as long as they don't touch an integration critical to home security.
Common Error Messages and What They Actually Mean
| Log message | Most common cause |
|---|---|
| Unable to connect / Connection refused | the device is offline, its IP address changed, or there's a network issue between VLANs (Lesson 8) |
| Config entry failed to setup | the integration needs reauthorization, usually also visible as an active Repairs entry |
| Detected blocking call inside the event loop | a technical problem in the integration's code, usually needs reporting to its author |
| Timeout waiting for response | an overloaded device or too slow a network, common with weak Wi-Fi signal |
When the Problem Isn't on Home Assistant's Side
Not every problem visible in Home Assistant's logs has its cause there. Before you spend an hour analyzing an integration's logs, it's worth checking the basics: does the device have power and is it online, did the router have an outage, did your internet provider have an issue affecting cloud integrations. System Health, covered at the start of this lesson, often shows outright whether the problem is on the network side, an integration provider's cloud, or Home Assistant itself, which helps you avoid hunting for a bug in the wrong place.
The Log as the System's Memory, Not Just an Emergency Tool
It's worth treating the System Log not only as a tool you reach for in a crisis, but as something you skim every so often even when nothing seems to be happening. A small, recurring warning, ignored for weeks, often precedes a more serious failure: an integration reporting occasional connection issues may eventually stop working entirely. A quick glance at the logs during the monthly review from Lesson 10 catches signals like these early, before they turn into a real problem.
How to Test This Lesson
1. Open System Health and review every health section reported by your integrations.
2. Check the Repairs page for active, unresolved problems.
3. Turn on debug logging for one chosen integration and see how the log detail level changes.
Common Mistakes
Skipping the Repairs page after an update: active problems sit unnoticed for weeks
Filing a bug report without debug-logging output: makes it much harder for anyone to help diagnose the problem
Looking for the home-assistant.log file after updating to 2025.11+: the file was removed from default access, you need the CLI instead
Practical Task
☐ Check System Health and Repairs on your install right now, whether or not anything seems broken.
☐ Learn to turn debug logging on and off for a chosen integration.
☐ Write down in your smart-home notebook where to find each of these three tools.
Key Takeaways
System Health is the first stop: a consolidated view of the whole install in one place.
Repairs shows active problems needing your intervention, check it after every update.
Per-integration debug logging gives the precise information you need for trickier problems.
What's Next
Next lesson: Users and Permissions: An Account for a Child, a Guest, and an Administrator. We move from technical diagnosis to access control.
