# How Home Assistant Configures Its Fault Handler and Logging System

> Discover how Home Assistant configures its fault handler and logging system. Learn about crash trace capture and async-safe logging architecture for robust automation.

- Repository: [Home Assistant/core](https://github.com/home-assistant/core)
- Tags: internals
- Published: 2026-02-28

---

**Home Assistant configures its fault handler using Python's `faulthandler` module in [`homeassistant/__main__.py`](https://github.com/home-assistant/core/blob/main/homeassistant/__main__.py) to capture crash traces to a fault file, while the logging system is initialized in [`homeassistant/bootstrap.py`](https://github.com/home-assistant/core/blob/main/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`](https://github.com/home-assistant/core/blob/main/homeassistant/__main__.py) to the bootstrap utilities in [`homeassistant/bootstrap.py`](https://github.com/home-assistant/core/blob/main/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`](https://github.com/home-assistant/core/blob/main/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:

```python
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:

```python
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`](https://github.com/home-assistant/core/blob/main/homeassistant/bootstrap.py) instantiates a `HomeAssistantQueueHandler` from [`homeassistant/util/logging.py`](https://github.com/home-assistant/core/blob/main/homeassistant/util/logging.py). This handler pushes every `logging.LogRecord` into a `SimpleQueue` rather than writing directly to disk or stdout:

```python
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`:

```python
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:

```bash
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:

```python
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`](https://github.com/home-assistant/core/blob/main/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`](https://github.com/home-assistant/core/blob/main/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`](https://github.com/home-assistant/core/blob/main/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`](https://github.com/home-assistant/core/blob/main/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`](https://github.com/home-assistant/core/blob/main/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`](https://github.com/home-assistant/core/blob/main/homeassistant/util/logging.py), ensuring log emission never blocks the event loop.
- **File persistence** uses a `RotatingFileHandler` configured in [`homeassistant/bootstrap.py`](https://github.com/home-assistant/core/blob/main/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`](https://github.com/home-assistant/core/blob/main/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`](https://github.com/home-assistant/core/blob/main/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`](https://github.com/home-assistant/core/blob/main/homeassistant/components/logger/__init__.py) exposes service calls and YAML configuration that allow dynamic level adjustments without requiring a full restart.