Short Answer: Fix the Last Change, Not the Whole House

If Home Assistant will not start after a YAML edit, the safest answer is usually to undo or correct the most recent configuration change, run a configuration check, and restart once. YAML is Home Assistant's text configuration format, and small details matter: indentation, missing colons, tabs, quotes, deleted include files, and old options can stop startup. The good news is that Home Assistant usually tells you where to look.

Start with the latest error, not the scariest symptom. If the normal UI opens, go to Settings > System > Logs and search for the file name or integration that failed. An integration is Home Assistant's connector for a device, service, or feature. If Home Assistant opened in Recovery Mode, use that minimal UI to read the same logs and fix the exact line. If the UI will not open, use the Home Assistant OS command line, Terminal & SSH app, Samba, Studio Code Server, File Editor, or another access method you already trust. The first command to try on Home Assistant OS is ha core check, because it checks whether the stored configuration is valid before you restart again.

Do not factory reset because a single YAML line broke. A factory reset turns a narrow configuration problem into a full rebuild.

Why This Keeps Happening

This is not a theoretical support question. A Home Assistant Community thread from April 5, 2025 shows a Core update landing in Recovery Mode because Home Assistant could not parse automations.yaml. A Reddit r/homeassistant thread about HomeAssistant 2025.12.0 described repairs for invalid template YAML followed by a reboot that did not come back cleanly. Another recent Reddit thread wrestled with ha core check path confusion, while a June 2026 automation-code discussion described using ha core check before restart as part of a safer workflow.

The official docs line up with those community patterns. Home Assistant documents configuration checks from the UI and CLI, Safe Mode for isolating custom integrations, and Recovery Mode as a minimal rescue path. The July 1, 2026 Home Assistant 2026.7 release also added grouped Update all buttons for integration and app updates, which is convenient when the system is healthy. During recovery, the better move is still one change at a time.

Safe Mode vs Recovery Mode

The names sound similar, but they answer different questions.

Mode What it means in the house Best use What not to assume
Recovery Mode Home Assistant could not start normally, so it opened a minimal working system for repair. Read logs, fix the exact YAML or startup problem, or restore a backup. It does not mean your devices or history were deleted.
Safe Mode Home Assistant Core starts without custom integrations, custom cards, or custom themes. Prove whether a custom integration, dashboard card, or theme is causing the failure. It is not a normal operating mode for the home.
Normal Mode Your usual integrations, automations, dashboards, and devices load. Use after the configuration check passes and the underlying error is fixed. A normal boot does not prove every automation is healthy. Check Repairs and Logs.

The Recovery Order to Try

  1. Stop changing things. Do not update more integrations, install HACS packages, delete files, or restart repeatedly. Preserve the evidence.
  2. Read the first real error. Check Settings > System > Logs, the Recovery Mode notification, or command-line logs. Look for a file path, line number, integration name, or missing include.
  3. Undo the last YAML change. If you added a template, automation, include, integration block, customize entry, or package file, comment out only that change and save.
  4. Run the configuration check. In the UI, use Developer Tools > YAML > Check configuration. On Home Assistant OS, use ha core check.
  5. Restart once. If the same error returns, read the new line number. If a different error appears, fix that one next.
  6. Restore a backup if the fix is not obvious. Use the newest backup from before the bad edit or failed update. Make sure the backup key or emergency kit is available before relying on encrypted backups.

Useful Commands on Home Assistant OS

Use these from the Home Assistant OS command line or from the Terminal & SSH app if it is already installed and running. If you are using Home Assistant Container or another install type, paths and commands can differ.

ha core check

Runs the Home Assistant Core configuration check against the stored configuration. This is the command Home Assistant documents for Home Assistant OS.

ha core restart --safe-mode

Restarts Home Assistant Core in Safe Mode so you can test whether custom integrations, custom cards, or custom themes are involved.

ha core logs

Shows Home Assistant Core logs from the CLI. If the UI is unreachable, this is often where the useful file path or integration name appears.

Plain-English warning: do not use random host commands from old forum posts unless you know which installation type you are using. Home Assistant OS, Container, Supervised, and Core installs do not all keep configuration files in the same place.

Common Fixes by Error Type

Error pattern What it usually means Practical fix
Parser error in configuration.yaml, automations.yaml, or an included file Bad indentation, a missing colon, a tab, an unmatched quote, or a list item in the wrong place. Fix the line named in the log, then run ha core check. YAML indentation uses spaces, not tabs.
Missing !include file The main config points at a YAML file that was renamed, deleted, or moved. Restore the file, correct the include path, or remove that include line if you no longer use it.
Option no longer valid after update A release changed or removed a manually configured option. Check every release note between your old version and target version, especially backward-incompatible changes.
Works in Safe Mode but not normal mode A custom integration, custom dashboard card, or custom theme is likely involved. Disable or update custom pieces one at a time. Avoid changing core configuration at the same time.
Recovery Mode returns after every restart The root startup problem is still present. Read the current log again. If the error is not obvious, restore the last known good backup.

When to Restore a Backup

Restore a backup when the error is not a single clear YAML fix, when configuration storage appears corrupted, when several custom integrations changed at once, or when the home needs to work again faster than you can debug. Home Assistant's 2025.1 release overhauled backups with automated backups, encrypted cloud backup storage, retention policies, and an emergency-kit workflow. That makes recovery much better, but only if the backup and its key are actually available.

Use this rule: if you know the exact line, fix the line. If you are guessing across many files, restore a backup and reproduce the change later in a safer window.

What Not to Do

  • Do not factory reset first. It is rarely the fastest path for a YAML mistake.
  • Do not delete .storage. That directory contains Home Assistant's internal storage. Deleting it can create a much larger problem.
  • Do not delete configuration.yaml unless you have a tested backup and a deliberate rebuild plan. A missing main config can create fresh errors and confusion.
  • Do not run Update all while recovering. In Home Assistant 2026.7, Update all is organized by update groups, but recovery calls for fewer variables, not more.
  • Do not let a half-fixed system control risky automations. Locks, garage doors, alarms, water valves, HVAC, and security notifications need manual fallback while the hub is unstable.

A Safer Workflow for Future YAML Edits

Most homeowners do not want a software deployment process for a smart home. Still, three small habits prevent most painful YAML incidents:

  1. Make one change at a time. Add one automation, one template, or one include, then validate.
  2. Check before restart. Use Developer Tools > YAML or ha core check before restarting Home Assistant Core.
  3. Keep an off-device backup. A backup stored only on the failed box is not a recovery plan.

If you maintain lots of YAML, consider keeping the files in a private Git repository or another versioned backup. You do not need a complex pipeline. You need the ability to see what changed yesterday.

How Tara Thinks About This

Tara's bias is to keep the house boring under failure. Local control means the hub can run routines inside the home instead of depending on a cloud service for every action. That is valuable only if the system is recoverable by a normal homeowner or a support handoff. That means fewer clever YAML one-offs, clear backup ownership, simple file access, and automations that fail visibly instead of silently.

In a Tara setup, YAML is treated as infrastructure. We use it where it makes the home clearer, not where it turns a hallway light or water sensor into a debugging project. The right recovery workflow is part of the design: local hub, clear device labels, backups, and enough documentation that the next person can fix the issue without guessing.

FAQ

Should I factory reset Home Assistant if it will not start?

No. Read the logs first, undo the last YAML or configuration change, run a configuration check, and restore a known good backup only if the specific fix is not clear.

What is the difference between Safe Mode and Recovery Mode?

Safe Mode is a troubleshooting startup path that leaves out custom integrations, custom cards, and custom themes. Recovery Mode is an automatic minimal startup mode Home Assistant uses when something prevents normal startup.

Can Recovery Mode delete my devices or history?

Home Assistant's Recovery Mode docs say it does not delete, reset, or modify your configuration, entities, or history. It starts a minimal system so you can investigate and fix the problem.

What if the UI never opens?

Use the access method you already prepared: local console, Terminal & SSH, Samba, Studio Code Server, File Editor, or a backup restore path. If you have none of those, stop power-cycling and get file access before making more changes.

Should I disable HACS or custom integrations?

If Home Assistant works in Safe Mode but not normally, HACS items or custom integrations are suspects. HACS is the community store many people use for unofficial Home Assistant add-ons, integrations, and dashboard cards. Disable or update those custom pieces one at a time after you have a backup.

Use the Home Assistant backup guide before the next big change. If this happened after a release, read how to update Home Assistant safely. If the issue is a stale template rather than a startup failure, start with why a template sensor is not updating. If devices disappear after the restart succeeds, use the unavailable-device checklist.