# Home Assistant Safe Mode: What It Is and When It's Triggered

> Discover Home Assistant Safe Mode, a minimal startup mode. Learn what triggers it manually or automatically after boot failures and how it helps keep your system running.

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

---

**Home Assistant Safe Mode is a minimal startup mode that loads only core integrations by checking for a `safe-mode` flag file in the configuration directory, triggered manually or automatically after critical boot failures.**

The **safe mode feature in Home Assistant** allows the platform to bypass potentially broken custom integrations and start with a barebones configuration. This recovery mechanism is implemented in the `home-assistant/core` repository as a disk-based flag system that persists across restarts to ensure the next boot occurs in a protected state.

## How the Safe Mode Feature Works

Home Assistant implements safe mode through a simple file-based flag mechanism that is checked during the bootstrap process and immediately cleaned up to prevent persistent safe mode loops.

### The Flag File Mechanism in config.py

The core logic resides in [`homeassistant/config.py`](https://github.com/home-assistant/core/blob/main/homeassistant/config.py). The `async_enable_safe_mode()` function creates a sentinel file named `safe-mode` in the configuration directory:

```python

# homeassistant/config.py lines 1372-1378

async def async_enable_safe_mode(hass: HomeAssistant) -> None:
    """Enable safe mode."""
    Path(hass.config.path(SAFE_MODE_FILENAME)).touch()

```

When Home Assistant starts, the `safe_mode_enabled()` function checks for this file's existence, records the result, and immediately deletes the file so the mode only applies to the current startup:

```python

# homeassistant/config.py lines 1360-1369

def safe_mode_enabled(config_dir: str) -> bool:
    """Check if safe mode is enabled."""
    safe_mode_path = os.path.join(config_dir, SAFE_MODE_FILENAME)
    if os.path.exists(safe_mode_path):
        os.remove(safe_mode_path)
        return True
    return False

```

### Bootstrap Detection in bootstrap.py

During startup, [`homeassistant/bootstrap.py`](https://github.com/home-assistant/core/blob/main/homeassistant/bootstrap.py) checks the `hass.config.safe_mode` attribute (set by the flag detection logic) and logs the mode change:

```python

# homeassistant/bootstrap.py lines 37-39

if hass.config.safe_mode:
    _LOGGER.info("Starting in safe mode")

```

### Runtime Configuration Storage

The safe mode state is stored on the `Config` dataclass in [`homeassistant/core_config.py`](https://github.com/home-assistant/core/blob/main/homeassistant/core_config.py) at line 605, where `self.safe_mode: bool = False` is defined as a default that gets overwritten during bootstrap if the flag file is present.

## When Home Assistant Safe Mode Is Triggered

Safe mode activates under two primary conditions: manual user intervention or automatic system protection after critical failures.

### Manual Activation

Users can trigger safe mode through the UI by selecting **Settings → System → Restart → Restart in safe mode**, which internally calls `async_enable_safe_mode()`. Alternatively, developers and operators can programmatically enable it:

```python
import homeassistant.config as config
await config.async_enable_safe_mode(hass)

```

This creates the `safe-mode` file in the configuration directory, ensuring the next boot skips all custom integrations.

### Automatic Recovery After Critical Failures

When [`homeassistant/bootstrap.py`](https://github.com/home-assistant/core/blob/main/homeassistant/bootstrap.py) encounters unrecoverable errors during startup—such as critical integration failures listed in `CRITICAL_INTEGRATIONS`—the system may automatically enable safe mode. Lines 49-55 of [`bootstrap.py`](https://github.com/home-assistant/core/blob/main/bootstrap.py) handle the transition to recovery state, which can indirectly trigger safe mode to prevent broken components from loading on the next restart.

### Safe Mode vs. Recovery Mode

While related, these are distinct states:
- **Safe Mode** skips loading custom integrations entirely based on the `safe-mode` flag
- **Recovery Mode** (also in [`bootstrap.py`](https://github.com/home-assistant/core/blob/main/bootstrap.py)) handles configuration parsing errors in [`configuration.yaml`](https://github.com/home-assistant/core/blob/main/configuration.yaml) and falls back to a minimal configuration

Safe mode specifically protects against broken custom code, while recovery mode handles fundamental configuration syntax errors.

## Detecting and Enabling Safe Mode Programmatically

Developers can check safe mode status at runtime to alter behavior:

```python

# Check if running in safe mode

if hass.config.safe_mode:
    _LOGGER.debug("Skipping custom component initialization")

```

The flag check function can also be used in standalone scripts:

```python
import os
from homeassistant.config import SAFE_MODE_FILENAME, safe_mode_enabled

config_dir = "/config"
if safe_mode_enabled(config_dir):
    print("Safe mode was enabled for this session")

```

Helper routines throughout the codebase, such as in [`homeassistant/helpers/check_config.py`](https://github.com/home-assistant/core/blob/main/homeassistant/helpers/check_config.py) (lines 137-138 and 282-283), use this flag to suppress error reporting for missing integrations when safe mode is active, preventing noise from expectedly absent custom components.

## Summary

- **Safe mode** loads only core integrations by checking for a `safe-mode` flag file in the configuration directory
- The flag is created by `async_enable_safe_mode()` in [`homeassistant/config.py`](https://github.com/home-assistant/core/blob/main/homeassistant/config.py) and consumed by `safe_mode_enabled()`, which deletes it after reading
- [`homeassistant/bootstrap.py`](https://github.com/home-assistant/core/blob/main/homeassistant/bootstrap.py) logs safe mode activation and alters the startup sequence accordingly
- The state is stored in `hass.config.safe_mode` as defined in [`homeassistant/core_config.py`](https://github.com/home-assistant/core/blob/main/homeassistant/core_config.py)
- Triggered manually via UI/API calls or automatically after critical integration failures
- Distinct from recovery mode, which handles YAML parsing errors rather than integration loading failures

## Frequently Asked Questions

### What is the difference between Home Assistant Safe Mode and Recovery Mode?

Safe mode specifically skips loading custom and third-party integrations by checking the `safe-mode` flag file, while recovery mode activates when [`configuration.yaml`](https://github.com/home-assistant/core/blob/main/configuration.yaml) contains syntax errors that prevent parsing. Recovery mode uses a minimal default configuration, whereas safe mode uses your existing configuration but ignores custom integration folders.

### How do I manually trigger Home Assistant Safe Mode from the command line?

Create an empty file named `safe-mode` in your Home Assistant configuration directory (e.g., `touch /config/safe-mode`), then restart the service. The `safe_mode_enabled()` function in [`homeassistant/config.py`](https://github.com/home-assistant/core/blob/main/homeassistant/config.py) will detect this file, remove it, and set `hass.config.safe_mode = True` for that session.

### Does Safe Mode delete my configuration files?

No. Safe mode only affects what integrations load during startup; it never modifies [`configuration.yaml`](https://github.com/home-assistant/core/blob/main/configuration.yaml), [`automations.yaml`](https://github.com/home-assistant/core/blob/main/automations.yaml), or other configuration files. The only file operation performed is the deletion of the temporary `safe-mode` flag itself after it is checked.

### Why does Home Assistant delete the safe-mode flag file after reading it?

The flag is designed as a single-use trigger to prevent the system from being permanently stuck in safe mode. By removing the file immediately upon detection in `safe_mode_enabled()`, Home Assistant ensures that the next restart will return to normal operation unless the flag is explicitly recreated due to another failure or manual request.