Short answer: if Home Assistant says it cannot restart because the configuration is not valid, do not keep restarting and do not delete large sections of YAML. First run the built-in configuration check, read the first concrete error, fix only that section, and validate again before reloading or restarting.
What the message means
Home Assistant checks configuration before a reload or restart. The failure may be a YAML syntax problem, an invalid option, a missing integration platform, an incorrect indentation level, or a file saved in the wrong encoding. The first error is usually the most useful one.
Safest diagnostic sequence
- Stop changing multiple files and note the last edit.
- Open Settings → Developer tools → YAML and run the configuration check. On Home Assistant OS or a supported CLI setup, use
ha core check. - Read the first specific file path, line number, integration name, or error message.
- Undo only the last risky change or restore the smallest known-good block.
- Run the check again before reloading or restarting.
Common causes
Indentation or punctuation
Check tabs, mismatched quotes, missing colons, duplicate keys, and list items that are not aligned. Compare the affected block with the current integration documentation.
Removed or renamed platforms
An old platform: entry can fail after an integration changes or a custom component is removed. Confirm whether the configuration should be migrated or removed.
Invalid options
Treat “extra keys not allowed” as a documentation mismatch, not a reason to guess. Check the current integration page and release notes.
Encoding or included files
Home Assistant documentation notes that configuration files must be UTF-8 encoded. If you use !include or packages, follow the path and inspect the child file too.
How to interpret the result
Validation passes: the configuration is acceptable to the check, but devices can still be offline. The same error remains: you may have edited the wrong file or missed an included file. A new error appears: fix one concrete error at a time and validate after each change.
Recovery if the UI will not restart
Use the last known-good backup or snapshot before making broad edits. Restore the smallest affected file first. Avoid deleting the whole configuration directory.
Prevention
- Run a configuration check before every restart after YAML edits.
- Make one focused change at a time.
- Keep dated backups before upgrades.
- Prefer UI-configured integrations when supported.
FAQ
Can I restart anyway?
Not safely. The warning exists to prevent a restart with a known-invalid configuration.
Will a configuration check find offline devices?
No. It checks configuration syntax and supported structure.
Should I delete the line named in the error?
Only if current documentation confirms it is obsolete or invalid.
Sources: Home Assistant troubleshooting; Home Assistant configuration and validation; Home Assistant OS configuration check.
Testing disclosure: Documentation-based guide; no hands-on testing on a specific installation is claimed.