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

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. The async_enable_safe_mode() function creates a sentinel file named safe-mode in the configuration directory:

# 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:

# 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 checks the hass.config.safe_mode attribute (set by the flag detection logic) and logs the mode change:

# 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 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:

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 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 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) handles configuration parsing errors in 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:

# 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:

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 (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 and consumed by safe_mode_enabled(), which deletes it after reading
• 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
• 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 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 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, 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.

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