How Home Assistant Configures Its Fault Handler and Logging System

Home Assistant configures its fault handler using Python's faulthandler module in homeassistant/__main__.py to capture crash traces to a fault file, while the logging system is initialized in homeassistant/bootstrap.py through async_enable_logging(), which implements an async-safe queue-based architecture with HomeAssistantQueueHandler and HomeAssistantQueueListener to prevent event loop blocking.

Home Assistant, the popular open-source home automation platform, implements a sophisticated fault handler and logging system to ensure crashes are diagnosable and log output never blocks the async event loop. The configuration spans multiple core modules, from the entry point in homeassistant/__main__.py to the bootstrap utilities in homeassistant/bootstrap.py. Understanding this architecture is essential for developers debugging production instances or contributing to the core platform.

Fault Handler Configuration in Home Assistant

The fault handler provides low-level crash diagnostics by intercepting fatal signals before the process terminates.

Enabling the Fault Handler at Startup

In homeassistant/__main__.py, Home Assistant imports Python's built-in faulthandler module at the top of the file. When the --log-fault command-line option is supplied, the application opens (or creates) a fault dump file—defaulting to home-assistant.log.fault—and registers the handler:

faulthandler.enable(fault_file)

This call registers faulthandler to catch fatal signals such as SIGSEGV, SIGABRT, and SIGBUS. When triggered, the handler writes a raw Python traceback to the specified fault file, providing a low-level view of the failure state without requiring external debuggers.

Disabling After Bootstrap

Once the core application has fully started and stabilized, Home Assistant disables the fault handler to avoid unnecessary file writes during normal operation. The bootstrap process calls:

faulthandler.disable()

This cleanup occurs after the initial setup phase, ensuring that only critical startup crashes are captured while runtime stability is assumed post-bootstrap.

Logging System Architecture

Home Assistant replaces Python's standard logging infrastructure with an async-safe pipeline that prevents blocking the event loop during high-volume log generation.

Async Queue Handler Implementation

The async_enable_logging() function in homeassistant/bootstrap.py instantiates a HomeAssistantQueueHandler from homeassistant/util/logging.py. This handler pushes every logging.LogRecord into a SimpleQueue rather than writing directly to disk or stdout:

queue_handler = HomeAssistantQueueHandler(queue)

By decoupling log emission from I/O operations, the system guarantees that components can log messages without yielding control or stalling the async event loop.

Background Queue Listener

Complementing the queue handler, HomeAssistantQueueListener runs in a dedicated background thread. It continuously pulls records from the queue and dispatches them to the actual output handlers:

• File output via RotatingFileHandler
• UI accessibility through the log viewer integration
• External services such as Syslog when configured

The listener implements rate-limiting logic to prevent a single noisy integration from flooding the log pipeline and exhausting system resources.

Rotating File Handler Configuration

The bootstrap process attaches a standard Python RotatingFileHandler to the listener. By default, this writes to home-assistant.log in the configuration directory with the following characteristics:

• Maximum file size: 5 MiB (configurable)
• Backup count: Configurable number of archived logs retained
• Rotation: Automatic rollover when size threshold is reached

This ensures that log files never grow unbounded, preventing disk space exhaustion on long-running installations.

Root Logger Replacement

To ensure universal adoption of the async-safe pipeline, async_enable_logging() clears any existing handlers from Python's root logger and attaches the HomeAssistantQueueHandler:

root_logger = logging.getLogger()
root_logger.handlers.clear()
root_logger.addHandler(queue_handler)

This replacement occurs before any integrations are loaded, guaranteeing that every component—from core to third-party—automatically benefits from the non-blocking logging infrastructure.

Practical Configuration Examples

Command Line Fault Dump

To enable crash trace capture during startup troubleshooting, launch Home Assistant with the fault logging flag:

hass --log-fault

This creates or overwrites home-assistant.log.fault in the working directory. If a fatal signal occurs during the bootstrap phase, the raw traceback will be available for post-mortem analysis.

Runtime Log Level Adjustment

After the logging system initializes, you can dynamically adjust verbosity without restarting the service:

import logging

# Enable debug logging for the core system

logging.getLogger("homeassistant.core").setLevel(logging.DEBUG)

Changes take effect immediately because the queue handler propagates all records regardless of level, leaving filtering to the listener and individual handler configurations.

Key Source Files and Implementation Details

File	Role	Direct Link
homeassistant/__main__.py	Entry point that enables/disables faulthandler and parses CLI arguments	https://github.com/home-assistant/core/blob/dev/homeassistant/__main__.py
homeassistant/bootstrap.py	Contains async_enable_logging() that constructs the queue handler, listener, and file rotation	https://github.com/home-assistant/core/blob/dev/homeassistant/bootstrap.py
homeassistant/util/logging.py	Implements HomeAssistantQueueHandler and HomeAssistantQueueListener classes	https://github.com/home-assistant/core/blob/dev/homeassistant/util/logging.py
homeassistant/components/logger/__init__.py	Exposes YAML configuration schema for custom log levels and service calls	https://github.com/home-assistant/core/blob/dev/homeassistant/components/logger/__init__.py

Summary

• Fault handling is managed through Python's faulthandler module in homeassistant/__main__.py, capturing fatal signal tracebacks to home-assistant.log.fault when --log-fault is specified and disabling after bootstrap completes.
• Async-safe logging is implemented via HomeAssistantQueueHandler and HomeAssistantQueueListener in homeassistant/util/logging.py, ensuring log emission never blocks the event loop.
• File persistence uses a RotatingFileHandler configured in homeassistant/bootstrap.py to maintain home-assistant.log with size-based rotation and backup retention.
• Universal coverage is achieved by replacing the root logger handlers during bootstrap, forcing all integrations to use the queue-based pipeline.

Frequently Asked Questions

What is the default fault file location in Home Assistant?

When using the --log-fault command-line option, Home Assistant creates the fault dump file at home-assistant.log.fault in the current working directory. This path is defined in homeassistant/__main__.py and can be overridden by specifying a custom path argument to the --log-fault flag.

How does Home Assistant prevent logging from blocking the event loop?

The platform implements a queue-based logging architecture where HomeAssistantQueueHandler places log records into a SimpleQueue rather than performing I/O directly. A background thread running HomeAssistantQueueListener consumes these records and dispatches them to actual handlers (file, UI, syslog). This decoupling ensures that calling logger.info() or logger.error() never yields or stalls the async event loop.

Where is the logging configuration initialized during startup?

The logging system is initialized in homeassistant/bootstrap.py within the async_enable_logging() function. This coroutine is called early in the bootstrap process, before any integrations are loaded. It constructs the queue handler, attaches the rotating file handler, and replaces the root logger's handlers to ensure the entire process uses the async-safe pipeline from startup.

Can I change the log level without restarting Home Assistant?

Yes, you can adjust log levels at runtime using Python's standard logging API or through the Logger integration. For programmatic changes, import the logging module and call logging.getLogger("homeassistant.core").setLevel(logging.DEBUG) to enable debug output immediately. Alternatively, the homeassistant/components/logger/__init__.py exposes service calls and YAML configuration that allow dynamic level adjustments without requiring a full restart.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}