Home Assistant YAML Errors: How to Find and Fix Them

Updated 9 November 2026 · Standard formula, shown below

Home Assistant YAML errors can prevent configuration changes or automations from loading. Use the built-in configuration check, read the reported file and line, and correct the syntax before restarting or reloading anything. You’ll need access to your configuration files and a recent backup or a copy of the file you plan to change.

What You’ll Need

Access to your Home Assistant configuration directory, through the File editor add-on, Studio Code Server, a network share, or another editor you already use.
A backup of the configuration files you are editing. At minimum, keep an untouched copy of the file before making changes.
Access to Home Assistant’s configuration check and logs. Menu labels can vary slightly by version and installation type.

Step-by-Step

Save a backup and identify the change. Before editing, copy the affected YAML file or create a Home Assistant backup. If the problem began after changing a particular automation, integration, or package, note exactly what changed. Avoid editing several unrelated files at once; a small, isolated change is easier to verify and undo.
Run the configuration check. In the Home Assistant interface, open Developer tools and look for the YAML or configuration-check action. Depending on the version, it may be labelled Check configuration or appear in the YAML section. Run the check before restarting. If you cannot access the interface, inspect the Home Assistant logs for configuration errors. The check can catch many YAML and configuration problems, but passing it does not guarantee every integration or automation will work at runtime.
Read the complete error message. Note the filename, line number, and wording. A message such as “mapping values are not allowed here” often points to a misplaced colon or indentation issue. “Expected a dictionary” or a message about a missing required key can indicate that a value has the wrong structure. Treat the indicated line as a clue, not proof that the mistake is on that exact line: YAML parsers sometimes report where they noticed a problem rather than where it began.
Open the named file and inspect the surrounding lines. Check several lines above and below the reported location. Confirm that the file is valid YAML and that the section matches Home Assistant’s expected configuration structure. If the error points to a file included from configuration.yaml, edit the included file rather than adding the same configuration elsewhere.
Fix indentation first. YAML uses spaces to show which values belong under a key. Use spaces consistently; do not use tabs. Child entries must be indented farther than their parent, and entries at the same level should line up. For example:
automation:
- alias: Evening lights
trigger:
- platform: sun
event: sunset
Here, the list item belongs under automation, and its trigger and event are nested beneath it. Match the indentation pattern used by the relevant section rather than adding spaces by guesswork.
Check colons, dashes, and quotes. A mapping uses a colon between a key and its value, while a list item starts with a dash. Look for a missing colon, an extra dash, or a value accidentally placed at the wrong nesting level. Quote text when it could be interpreted as YAML syntax, especially values beginning with special characters. Make sure quoted strings have matching opening and closing quotes. Avoid changing a value’s meaning just to silence a parser error.
Check lists, duplicate keys, and special values. Items in a list need consistent indentation and a dash. Check that a key has not been repeated at the same level: duplicate keys may cause confusing results or warnings. YAML also treats values such as true, false, and null specially. Use the intended value and follow the syntax expected by that Home Assistant option; do not quote a Boolean or null unless the configuration specifically expects text.
Check the configuration schema and included files. Valid YAML can still be invalid Home Assistant configuration. Verify that the option name and nesting are supported for the integration or feature you are configuring, using its current Home Assistant documentation. Check that each file referenced with an include exists, is spelled correctly, and contains the structure expected by that include. Do not assume an older example still uses the current schema.
Save, check again, then apply the change. Save the file and run the configuration check again. If it passes, use the relevant reload action for that feature when available. If a full restart is required, restart Home Assistant only after the check passes, then confirm the feature works and review the logs. A successful syntax check does not verify credentials, device availability, or every runtime dependency.
Undo safely if the error persists. If you cannot identify the cause, restore the original file or revert only the latest change. Run the check again to confirm you are back to a known-good state. Then reapply the change in smaller pieces, checking after each one.

Common Mistakes

Using tabs, inconsistent indentation, or spaces at the wrong nesting level is a frequent cause of parser errors. YAML is whitespace-sensitive, so visually similar lines may not mean the same thing.

Another common mistake is treating YAML validity as proof that a Home Assistant option is correct. A misspelled key can be syntactically valid but unsupported. Check both the parser message and the current documentation for the integration or feature.

Be careful when copying snippets from examples. A snippet may assume a particular location, indentation level, or configuration style. Pasting it at the top level when it belongs inside a list or another key can break the file. Also avoid broad search-and-replace edits: they can change valid entries elsewhere.

Tips

Use an editor that displays indentation and can convert tabs to spaces. If you are unsure whether a file contains tabs, enable visible whitespace or use the editor’s indentation settings.
Keep configuration changes small and make a quick copy before each substantial edit.
Use consistent formatting and descriptive names. Clear structure makes it easier to compare a file with a documented example.
When reporting an error for help, include the full message and a small, relevant excerpt with private details removed. Do not post passwords, access tokens, or other secrets.
Prefer the configuration method documented for the feature you are setting up. Some settings are managed through the Home Assistant interface rather than by adding YAML manually.

Troubleshooting

The check reports a line that looks correct: Inspect the preceding lines for an unclosed quote, misplaced list dash, or indentation problem. The parser may only detect the issue after the line where it started.

The check passes, but the feature does not work: Read the logs after reloading or restarting. Look for a schema warning, missing integration, invalid option, unavailable device, or authentication problem. These are not necessarily YAML syntax errors.

The interface is unavailable after an edit: Use the access method available for your installation to open the configuration files and logs. Restore the last known-good copy if needed, then restart only when you can confirm the configuration is valid. If you cannot safely recover, use your backup and the recovery guidance for your installation type.

An include or package causes the error: Check the path and filename, then inspect the included file itself. Confirm its contents are shaped for the include method in use; an include expecting a list will not accept an unrelated mapping structure.

The error began after an update: Compare the configuration with the current documentation for the affected feature. A previously accepted option may have changed or been removed. Avoid guessing at replacements; verify the supported format before editing.

Frequently Asked Questions

Does a successful configuration check mean everything is working?
No. It checks configuration syntax and some configuration requirements, but it cannot guarantee that devices, credentials, or integrations work at runtime.

Should I restart Home Assistant after every YAML edit?
No. Run the check first, then use the relevant reload action if the feature supports it. Restart only when required for the change.

Why does the error point to the wrong line?
The parser may detect a problem only when it reaches a later line. Check the reported location and the lines immediately before it.

Can I use tabs for YAML indentation?
No. Use spaces for indentation. Tabs can make YAML invalid even when the file looks aligned in an editor.

Is valid YAML always valid Home Assistant configuration?
No. The syntax may be valid while an option name, value, or nesting level is unsupported. Check the current documentation for that feature.

What should I do if I cannot find the error?
Restore the last known-good copy, run the check, and reintroduce the change in small steps. Use the full error message and relevant, redacted lines to seek help.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.