Recovery mode

The Recovery mode integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] is an internal integration that Home Assistant activates automatically when, in rare cases, something unexpected prevents it from starting normally. It is a safety net. Home Assistant is designed to handle updates, configuration changes, and day-to-day operation without needing recovery mode, and in practice, you are unlikely to ever see it.

When it is needed, recovery mode gives you a minimal but working Home Assistant so you can investigate and fix the problem without having to edit files directly on disk.

You do not install or configure this integration. Home Assistant starts it for you when needed.

When Home Assistant starts in recovery mode

Recovery mode is rarely needed. Home Assistant only falls back to it when something unexpected prevents a normal startup, for example:

• The configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file cannot be parsed because of a YAML syntax error.
• A manually edited configuration file contains options that are no longer valid.
• One or more core integrationsIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more], such as the frontend, fail to load due to an unexpected environmental issue.
• The configuration storage was corrupted, for example, after a sudden power loss.

When recovery mode is active, Home Assistant loads only a minimal set of system integrationsIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] (such as the frontend, backup, and cloud) and skips all your user-configured integrationsIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more]. You see a Recovery Mode notification on the dashboard when you sign in.

What to do when you are in recovery mode

1. Open Settings > System > Logs and look for the error that caused the problem. The log entry usually points at the exact line in configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] or the integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] that failed.
2. Fix the reported issue. This often means:
   • Correcting a YAML syntax error in configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more].
   • Removing or updating a configuration option that was changed. Check the backward-incompatible changes of a recent release if the issue appeared after an update.
   • Restoring a backup from before the problem started.
3. Restart Home Assistant from Settings > System by selecting Restart Home Assistant, or by rebooting your host.
4. If Home Assistant starts normally, the issue is resolved. If recovery mode reactivates, the underlying issue is still there. Check the logs again for the current error.

Common causes

When recovery mode does happen, these are the most common reasons:

• YAML syntax errors: incorrect indentation, missing colons, or unmatched quotes in configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] or any included YAML files.
• Missing include files: an !include reference in configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] points to a file that no longer exists.
• Backward-incompatible changes after an update: a manually configured option was changed or removed in a release. Check the backward-incompatible changes section of the release notes for the version you upgraded to.
• Corrupted configuration storage: it can happen after a sudden power loss during a write.

Known limitations

• In recovery mode, your integrationsIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more], devicesA device is a model representing a physical or logical unit that contains entities., automationsAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [Learn more], and scriptsScripts are components that allow you to specify a sequence of actions to be executed by Home Assistant when turned on. [Learn more] are not active. Recovery mode is only meant for fixing the problem, not for continuing to run Home Assistant.
• The recovery mode notification disappears as soon as Home Assistant starts normally again.