Exception Debug for Home Assistant

A live post-mortem debugger for Home Assistant exceptions — think pyramid_debugtoolbar or the Werkzeug interactive debugger, but for Home Assistant and queryable by an AI agent over MCP.

Home Assistant's built-in system_log keeps only the formatted text of an error. This integration keeps the live exception object and its traceback frames in memory for a short window, so you (or an AI coding agent) can:

• list recently captured exceptions,
• walk each traceback's frames and read their local variables, and
• optionally evaluate Python in the context of a captured frame for true post-mortem debugging.

⚠️ This is a developer/debugging tool. Retaining tracebacks pins the objects that were in scope when the error happened, and the eval_in_frame capability is arbitrary code execution by design. Keep enable_eval off unless you understand the implications, and never expose your Home Assistant instance unauthenticated.

How it works

A logging.Handler is attached directly to the root logger during setup. Because Home Assistant migrates its console/file handlers behind a QueueHandler (whose prepare() strips exc_info) before any integration loads, a sibling root handler added afterwards still sees records with their live exc_info intact — the same mechanism the core system_log integration relies on. When a record arrives with no exc_info (e.g. Home Assistant's catch_log_exception logs pre-formatted text), the handler falls back to sys.exc_info(), which is still valid because it runs synchronously inside the originating except block.

Captured exceptions are held in a bounded, TTL-aware store. Once an entry's live window (ttl) elapses — or it is evicted past max_entries — its frames are cleared with traceback.clear_frames() to release locals, while a text snapshot of the traceback is retained so the entry stays listable. A timer applies the TTL once a minute, so frames are released on a quiet system too and not only when the next exception happens to arrive.

Requirements

• Home Assistant 2025.8.0 or newer.
• For the AI/agent path, the core Model Context Protocol Server integration. See Using it with an AI agent (MCP) — if you already have it configured, it has to be deleted and re-added, because it has no options flow. The REST and WebSocket APIs work without it.

Installation (HACS)

1. In HACS, add this repository as a custom repository (category: Integration): https://github.com/bbangert/ha-exception-debug.
2. Install Exception Debug and restart Home Assistant.
3. Go to Settings → Devices & services → Add integration and pick Exception Debug.
4. Only if you want the AI/agent path: set up (or re-add) the Model Context Protocol Server integration — see Using it with an AI agent (MCP). Do this after step 3, so Exception Debug is available to select.

Manual install: copy custom_components/exception_debug/ into your Home Assistant config/custom_components/ directory, restart, then add the integration from the UI as above.

Configuration

Everything is configured from the UI — on first setup, and afterwards via Settings → Devices & services → Exception Debug → Configure. Changing an option reloads the integration immediately; no restart needed.

Option	Default	Meaning
Capture level	error	Minimum log level to capture (debug … critical).
Maximum retained exceptions	50	Oldest are evicted past this count.
Live frame retention	900 s	How long an entry keeps inspectable frames. 0 releases them immediately.
Maximum repr length	2000	Cap on the characters returned for any single value.
Enable eval	off	Allows eval_in_frame — arbitrary code execution.

Only one instance can be configured, since the capture hook is global.

Migrating from YAML

Earlier versions were configured in configuration.yaml. That still works for one more startup: the block is imported into a config entry automatically and a repair issue tells you to delete it. Remove the exception_debug: block from configuration.yaml once you have restarted — after the import, the YAML is ignored and the UI options are authoritative.

Using it with an AI agent (MCP)

This integration does not speak MCP itself. It registers a Home Assistant LLM API named "Home Assistant Exception Debugger", which the core Model Context Protocol Server integration exposes to agents. You need that integration set up as well — without it there is no MCP endpoint and the tools below are unreachable.

⚠️ If you already have the MCP Server integration configured, you must delete its config entry and add it again. It has no options flow, so the set of exposed APIs is fixed when the entry is created and cannot be edited afterwards. It also allows only one entry, so you cannot add a second alongside the existing one.

If you do not have MCP Server yet

1. Set up Exception Debug first (above). The MCP Server flow lists the APIs that are registered at the moment you run it, so this one has to be loaded already or it will not appear as a choice.
2. Add the Model Context Protocol Server integration.
3. In the setup dialog, the API field is a multi-select. Tick both Assist and Home Assistant Exception Debugger (it defaults to Assist alone).
4. Point your MCP client at https://<your-ha>/api/mcp with a long-lived access token.

If you already have MCP Server configured

1. Set up Exception Debug first (above), so it is available to select.
2. Go to Settings → Devices & services → Model Context Protocol Server and delete the existing entry. Nothing else is lost — the entry stores only which APIs to expose.
3. Add the integration again. The API field is a multi-select, so tick both Assist and Home Assistant Exception Debugger to keep your existing Assist behaviour alongside the new tools.
4. Your existing MCP client configuration and token continue to work — the endpoint is unchanged.

Tools exposed to the agent:

Tool	Purpose
list_exceptions	Recent captured exceptions, newest first.
get_traceback	Full formatted traceback text for an id.
get_frames	Frames of an exception (file, line, function, local names).
get_frame_locals	{name: repr} of a frame's locals.
eval_in_frame	Evaluate Python in a frame's context (only if enable_eval: true).

REST API

All endpoints require an admin user's token (Authorization: Bearer <long-lived token>). Frame locals routinely contain credentials that were in scope when the error happened, so authentication alone is not a sufficient boundary — this matches the admin gate on the WebSocket commands.

GET /api/exception_debug/exceptions?limit=20
GET /api/exception_debug/exceptions/{id}
GET /api/exception_debug/exceptions/{id}/frames/{frame_index}/locals

WebSocket API (admin only)

exception_debug/list          {limit?}
exception_debug/frames         {exc_id}
exception_debug/frame_locals   {exc_id, frame}

Services

• exception_debug.clear — drop all captured exceptions and release frames.

Notes & limitations

• Root-logger handlers do not see loggers with propagate = False (rare in HA).
• Captured exceptions are held per config entry, so changing an option (which reloads the integration) starts a fresh buffer and discards what was captured.
• eval_in_frame runs on the event loop; a blocking snippet will block Home Assistant. Use it deliberately.
• The icon ships in-repo under custom_components/exception_debug/brand/, which satisfies the HACS brands check. Adding exception_debug to home-assistant/brands is only needed to appear in the default HACS store.

Development

python -m venv .venv && .venv/bin/pip install -r requirements_test.txt
.venv/bin/pytest --cov=custom_components.exception_debug --cov-branch --cov-report=term-missing
.venv/bin/ruff format --check custom_components tests
.venv/bin/ruff check custom_components tests
.venv/bin/mypy custom_components/exception_debug --ignore-missing-imports

CI runs hassfest, HACS validation, ruff, mypy, and the test suite on every push and pull request. Tests are gated at 100% branch coverage and run against both the minimum supported Home Assistant (2025.8.1) and a current release, so the version floor advertised in hacs.json is actually exercised rather than assumed.

License

MIT — see LICENSE.