ha-validate

description	Validate Home Assistant YAML for syntax errors, undefined secrets, and duplicate keys. Use when validating HA config, diagnosing YAML errors, or running hass check_config.
args	[path]
allowed-tools	Bash(python3 *), Bash(docker exec *), Bash(ha *), Read, Grep, Glob
argument-hint	Optional path to config directory (defaults to current directory)
created	"2025-02-01T00:00:00.000Z"
modified	"2026-06-18T00:00:00.000Z"
reviewed	"2026-04-25T00:00:00.000Z"
name	ha-validate

/ha:validate

Validate Home Assistant configuration files for YAML syntax errors and common issues.

When to Use This Skill

Use this skill when...	Use ha-configuration instead when...
Checking YAML syntax in configuration.yaml or automations.yaml	Editing configuration.yaml to add or change integrations
Detecting undefined !secret references against secrets.yaml	Adding new entries to secrets.yaml
Finding duplicate keys in scripts.yaml or scenes.yaml	Reorganizing configuration into packages
Running hass --script check_config via Docker or HA OS	Authoring template sensors and recorder/logger config

Context

• Config path: {{ path or '.' }}
• YAML files: !find . -name "*.yaml" -type f

Validation Steps

1. YAML Syntax Validation

Validate all YAML files for proper syntax:

find {{ path or '.' }} -name "*.yaml" -type f -exec python3 -c "
import yaml
import sys
try:
    with open('{}', 'r') as f:
        yaml.safe_load(f)
    print('OK: {}')
except yaml.YAMLError as e:
    print('ERROR: {}')
    print(str(e)[:200])
    sys.exit(1)
" \; 2>&1 | head -50

2. Check for Common Issues

Check for undefined secrets:

# Find secret references
grep -rh "!secret [a-z_]*" {{ path or '.' }} --include="*.yaml" 2>/dev/null | \
  sed 's/.*!secret //' | sort -u > /tmp/used_secrets.txt

# Check if secrets.yaml exists
if [ -f "{{ path or '.' }}/secrets.yaml" ]; then
  echo "secrets.yaml found"
  # List defined secrets
  grep "^[a-z_]*:" {{ path or '.' }}/secrets.yaml | sed 's/:.*//' | sort -u > /tmp/defined_secrets.txt
  echo "Undefined secrets:"
  comm -23 /tmp/used_secrets.txt /tmp/defined_secrets.txt
else
  echo "WARNING: secrets.yaml not found"
fi

Check for duplicate keys:

python3 -c "
import yaml
import sys
from collections import Counter

class DuplicateKeyChecker(yaml.SafeLoader):
    def construct_mapping(self, node, deep=False):
        keys = [k.value for k, v in node.value if isinstance(k, yaml.ScalarNode)]
        duplicates = [k for k, count in Counter(keys).items() if count > 1]
        if duplicates:
            print(f'Duplicate keys in {node.start_mark}: {duplicates}')
        return super().construct_mapping(node, deep)

for f in ['configuration.yaml', 'automations.yaml', 'scripts.yaml', 'scenes.yaml']:
    path = '{{ path or '.' }}/' + f
    try:
        with open(path) as file:
            yaml.load(file, Loader=DuplicateKeyChecker)
            print(f'OK: {f}')
    except FileNotFoundError:
        pass
    except yaml.YAMLError as e:
        print(f'ERROR in {f}: {e}')
" 2>&1

3. Docker-based Full Validation (if available)

If Home Assistant is running in Docker:

docker exec homeassistant hass --script check_config 2>&1 | head -100 || echo "Docker validation not available"

4. Home Assistant OS Validation (if available)

ha core check 2>&1 || echo "HA OS validation not available"

Post-Validation

Report validation results:

• List any YAML syntax errors with file and line numbers
• List any undefined secret references
• List any duplicate keys
• Suggest fixes for common issues

Common Fixes

Issue	Fix
found undefined alias	Add missing entry to secrets.yaml
could not determine a constructor	Check YAML indentation
duplicate key	Remove or rename duplicate key
expected <block end>	Fix indentation alignment
mapping values are not allowed	Add space after colon