| name | ha-troubleshooting |
| description | Docs-backed Home Assistant troubleshooting playbook — config check, logs, traces, Developer Tools, debug logging. Use when an automation, integration, or entity is failing, erroring, or misbehaving. |
HA Troubleshooting Playbook
When to use
- An automation, integration, or entity is failing, erroring, or misbehaving.
- The user asks to debug, diagnose, or investigate a problem.
Prerequisites
- Always re-fetch config snapshots for debugging — logs and state change frequently. Invoke the
ha-config-fetch skill instead of reading ha-data/ directly.
- Use the
ha-docs-sitemap skill to look up docs for the failing integration or feature before answering.
Playbook
Run these in order, stopping when the cause is found:
- Validate configuration — Settings → System → Repairs → Check configuration.
- Review logs — Settings → System → Logs; for raw logs invoke the
ha-config-fetch skill and read core.log / supervisor.log from the refreshed snapshots.
- Inspect automation traces — Automations → select automation → Traces.
- Use Developer Tools — States, Services; Template editor to test Jinja.
- Enable debug logging for the specific integration per the official docs.
Rules
- Cite the exact docs section used for each step (see
ha-docs-sitemap).
- Prefer supported features; avoid unsupported hacks.
- Recommend a backup before major config changes.
