Home Assistant Best Practices

Core principle: Use native Home Assistant constructs wherever possible. Templates bypass validation, fail silently at runtime, and make debugging opaque.

No tool reaches the HA API? Do not stop to ask for access. If you can drive a browser on the HA web UI, make the change there, but first show the user the exact change and wait for their OK before you save: approving a click does not show them what it writes. Otherwise give the user the complete config to create in the UI (for an automation, the YAML for the editor's Edit in YAML mode; for a helper, its form fields), and name the entity IDs you assumed. Config that can only be written in YAML is edited with the File editor app (or in the config folder on a Container install): keep a copy of the file first, then check the configuration and run the matching reload in the YAML tab of Tools (named Developer Tools before 2026.8; restart if it isn't listed).

A feature marked with a release (2026.5+) depends on the instance's version. Read it before choosing: version in GET /api/config, or Settings → About in the UI. On that release or later, use the feature and do not offer the older way as an equal choice. If you cannot read the version, assume a current release and name the older fallback with the version it needs.

Read the matching reference before you answer. This page only summarizes the files in Reference Files; the exact keys, fields and working examples are in them. Read every file whose row matches the task, and only those: do not load all reference files upfront.

Decision Workflow

Follow this sequence when creating any automation:

0. Gate: modifying existing config?

If your change affects entity IDs, display names, or cross-component references — renaming entities or devices, replacing template sensors with helpers, converting device triggers, or restructuring automations — read safe-refactoring first. That reference covers impact analysis, device-sibling discovery, display-name overrides, and post-change verification. Complete its workflow before proceeding.

Steps 1-5 below apply to new config or pattern evaluation.

1. Check for a purpose-specific, then generic native, trigger/condition

Since 2026.7 the default building blocks are purpose-specific triggers/conditions — <domain>.<name> keys (motion detected, battery low, door opened) with area/floor/label targets. Check for one that matches the intent first, then a generic native trigger/condition, and only then a template. Read triggers-and-conditions #purpose-specific-triggers--conditions-default-since-20267 before writing the trigger.

A purpose-specific trigger takes entity_id in its target: as well, so one known sensor is not a reason to fall back to trigger: state. Write the automation with the purpose-specific trigger; do not offer it only as an optional upgrade.

Common substitutions:

• trigger: state on a motion, occupancy or door binary_sensor → motion.detected/motion.cleared, occupancy.detected/occupancy.cleared or door.opened/door.closed with target: {entity_id: ...}, or area_id when the area is known
• List of individual sensor entities in a trigger → one purpose-specific trigger with an area/floor/label target:
• delay after motion.detected for "no motion anywhere for N minutes" → motion.cleared with options: {behavior: all, for: ...}, which fires once every targeted sensor has been clear that long (unavailable and unknown sensors are left out of the count)
• {{ states('x') | float > 25 }} → numeric_state condition with above: 25
• {{ is_state('x', 'on') and is_state('y', 'on') }} → condition: and with state conditions
• {{ now().hour >= 9 }} → condition: time with after: "09:00:00"

2. Check for built-in helper or Template Helper

Read helper-selection before creating a template sensor.

Common substitutions:

• Sum/average multiple sensors → min_max integration
• Binary any-on/all-on logic → group helper
• Rate of change → derivative integration
• Cross threshold detection → threshold integration
• Consumption tracking → utility_meter helper

If no built-in helper fits, use a Template Helper — not YAML. Create it via the HA config flow (programmatically or in the UI: Settings → Devices & Services → Helpers → Create Helper → Template). A flow-created helper is UI-editable; a template: YAML entry needs a template.reload and is not.

Write template: YAML when the user asks for it, when neither path is available, or when the config needs a key the flow has no field for — trigger-based templates and attributes: are the common ones. Then use managed YAML editing (yaml-only-integrations), not a hand-edit.

3. Select correct automation mode

Default single mode is often wrong. See automation-actions #automation-modes.

Scenario	Mode
Motion light with timeout	restart
Sequential processing (door locks)	queued
Independent per-entity actions	parallel
One-shot notifications	single

4. Use entity_id over device_id

device_id breaks when devices are re-added. See device-control.

Exception: Zigbee2MQTT autodiscovered device triggers are acceptable.

5. For buttons and remotes

• Any integration exposing an event.* entity: Use event.received targeting that entity (see the anti-pattern row below)
• ZHA: No event entities — use an event trigger with device_ieee (persistent)
• Z2M: Event entities are experimental and off by default — use a device trigger (autodiscovered) or mqtt trigger

Read device-control #buttonremote-patterns before writing the trigger.

---

Critical Anti-Patterns

Anti-pattern	Use instead	Why	Reference
condition: template with float > 25	condition: numeric_state	Keys and threshold are checked at load; an unavailable or unknown state is false, where float with no default raises an error	triggers-and-conditions #native-conditions
wait_for_trigger with a state trigger for a condition that may already hold	wait_template	A state trigger fires only on a transition, so the wait lasts until the entity leaves the state and re-enters it, or forever without a timeout (see safe-refactoring #trigger-restructuring)	automation-actions #wait-actions
device_id in triggers	entity_id (or device_ieee for ZHA)	device_id breaks on re-add	device-control #entity-id-vs-device-id
event trigger on an integration's bus event (e.g. hue_event) for a button that has an event.* entity	event.received targeting that entity, with values read from its event_types attribute	The entity can be renamed and survives a re-add when the integration keeps a stable unique ID; bus event data differs per integration	device-control #buttonremote-patterns
numeric_state trigger driving a costly action, unguarded	Condition rejecting unavailable/unknown in trigger.from_state	A restart or blip re-arms the trigger, so an unchanged value fires with no crossing (the guard also drops real crossings)	triggers-and-conditions #unavailable-arms-a-numeric-state-trigger
mode: single for motion lights	mode: restart	Re-triggers must reset the timer	automation-actions #automation-modes
enabled: false as a top-level key in automations.yaml	automation.turn_off (temporary) or entity registry disable (permanent)	Not a valid top-level key — rejected during schema validation; automation loads as unavailable	automation-actions #disabling-automations
Template sensor for sum/mean	min_max helper	Declarative, handles unavailable states	helper-selection #numeric-aggregation
Template binary sensor with threshold	threshold helper	Built-in hysteresis support	helper-selection #threshold
Renaming entity IDs without impact analysis	Follow safe-refactoring workflow	Renames break dashboards, scripts, scenes, Config-Entry data, and storage dashboards silently	safe-refactoring #entity-renames
Renaming members of Config-Entry-based groups (UI groups) without updating membership	Update group membership via Options Flow after the registry rename	The entity registry rename does not update options.entities in the Config Entry — group silently breaks	safe-refactoring #config-entry-groups
Renaming entities used by Min/Max helpers or custom Config-Entry integrations (e.g. Better Thermostat) without checking their Config-Entry data	Scan the config entries' data+options; re-select the renamed entity in the Min/Max Options Flow. An integration that keeps it in data (Better Thermostat) has no API fix: tell the user and take a full backup before the rename	They store entity_ids in the Config Entry, and a registry rename does not update them; single-source helpers such as Threshold (since 2025.6) and Generic Thermostat update themselves	safe-refactoring #config-entry-data--blind-spots-for-entity-registry-renames
template: sensor/binary sensor in YAML	Template Helper via the config flow	A flow helper reloads in place and stays UI-editable; a template: entry needs a config reload and does not. Exceptions are real — trigger-based templates and attributes: have no flow field	helper-selection #template-helpers
Editing .storage/ files or other HA internal state directly	Use the HA REST/WebSocket API to manage state and config entries	.storage/ files are HA's internal state database; direct edits bypass validation, risk corruption, and can be silently overwritten by HA	—
Looking for automation config in .storage/	Read and write automations through the HA config API. UI-created ones are saved to automations.yaml	No .storage/ file holds automation config, in any config mode. .storage/ holds only the automations' entity registry entries	—
Writing raw YAML to configuration.yaml by hand for YAML-only integrations	Use managed YAML config editing with backup and validation	Unmanaged writes risk syntax errors, have no backup, and skip check_config — managed editing provides all three	yaml-only-integrations
Generating YAML snippets for automations/scripts/scenes	Use the HA config API to create automations/scripts programmatically; with no API access, give the config for the UI editor instead	API calls validate config, avoid syntax errors, and don't require manual file edits or restarts	triggers-and-conditions, automation-actions, examples.yaml
Telling user to edit configuration.yaml for integrations	Direct user to Settings > Devices & Services in the HA UI	Most integrations are UI-configured; YAML integration config is rare and integration-specific	—
Referring to HA "add-ons"	Use the term "Apps"	HA renamed add-ons to Apps in 2026.2 — "Apps are standalone applications that run alongside Home Assistant"	—
vacuum.send_command with vendor room IDs	vacuum.clean_area with HA area IDs in cleaning_area_id (if segments are mapped)	Uses native HA areas, works across integrations — but requires segment-to-area mapping in entity settings first	device-control #vacuum-control
Using color_temp (mireds) in light actions	Use color_temp_kelvin with the value converted: Kelvin = 1,000,000 ÷ mireds (500 mireds = 2000 K)	The color_temp parameter was removed in 2026.3; only Kelvin is supported, and HA accepts any positive number there, so a mireds value copied across is read as Kelvin (500 mireds becomes 500 K)	device-control #lights
Saving states or attributes in variables:, or hard-coding values, to put devices back after a temporary change	scene.create with snapshot_entities before the change, then scene.turn_on on that scene	The snapshot keeps each entity's own state, including a light that was off, in one call; variables need a template per attribute and a restore step per entity	scenes #snapshot--restore-scenecreate
Person/Device Tracker entered_home/left_home device triggers or is_home/is_not_home conditions	state trigger to: home / to: not_home, or state condition	These were removed in 2026.5 — state triggers and conditions are the correct replacements	triggers-and-conditions #presence-and-person-triggers-and-conditions-removed-in-20265
Entity list in a trigger where an area/floor/label target fits	Purpose-specific trigger with target: {area_id: ...}	Automation follows area membership as devices change — no stale entity lists	triggers-and-conditions #purpose-specific-triggers--conditions-default-since-20267
Old purpose-specific keys (battery.low, vacuum.docked, timer.time_remaining, ...) or trigger behavior: any/last	Renamed 2026.7 keys (battery.became_low, ...) and behavior: each/all (renamed 2026.6)	Old keys no longer load; old behavior values raise a repair issue and face removal	triggers-and-conditions #purpose-specific-triggers--conditions-default-since-20267
AppDaemon: callbacks in __init__, uncancelled run_in timers, state in instance variables, hardcoded entity IDs	Register in initialize(), cancel before rescheduling, persist via input_* helpers, pass IDs through self.args	Each fails silently, resets on reload, or blocks reuse	appdaemon #appdaemon-specific-anti-patterns
Blueprints: hardcoded entities, free text where a selector belongs, !input inside a template, missing source_url	Typed !input selectors; bind an input to variables: before templating it; always set source_url	Hardcoding defeats reuse, text lets typos through, and !input is a YAML tag rather than a template value	blueprint-guide #common-pitfalls
Backups: full restore to undo one object edit, no backup before an irreversible operation (registry deletion, integration removal, Core/OS upgrade), calling an action "reversible" without naming its inverse	Roll the single object back; take the backup before; name the exact inverse or treat it as irreversible	A full restore reverts every unrelated change since and restarts HA; a backup taken afterward captures the damage	backups #when-a-full-backup-earns-its-cost
Restoring a backup, deleting a backup, or upgrading Core or the OS without explicit user confirmation	Ask, name the concrete effect, and wait for an answer — every time, backup or not	A full restore discards everything since the archive for all restored parts and restarts HA; a Supervisor partial restore overwrites only the selected archive parts; deletion destroys a recovery point; a Core/OS upgrade is high-impact and its recovery path IS the pre-upgrade backup	backups
The same non-trivial Jinja expression repeated across templates	Once a native trigger/condition and a built-in helper are ruled out, define it once as a macro in config/custom_templates/*.jinja and import it	One definition to fix when the rule changes, instead of copies that drift apart	template-guidelines #reusable-macros
trigger, this, value_json, or a {% set %} variable used inside an imported macro	Pass it to the macro as an argument	An import does not carry the caller's context — the variable is undefined inside the macro, so it renders empty and any attribute access on it errors (HA's own functions like states are globals and do work)	template-guidelines #imports-do-not-carry-the-callers-context

---

Reference Files

Read each file whose row matches the task before you answer:

File	When to read
safe-refactoring	Renaming entities or their display names, replacing helpers, restructuring automations, or any modification to existing config
triggers-and-conditions	Writing an automation's triggers or conditions: purpose-specific and native triggers/conditions, for: durations, trigger IDs
automation-actions	Writing the actions of an automation or script, or choosing its mode: waits, variables, capturing action responses, continue_on_error, admin-only actions (Unauthorized) in scripts, stopping a sequence, repeat, if/then vs choose, parallel; documenting/annotating steps; disabling automations
helper-selection	Deciding whether to use a built-in helper vs template sensor — aggregation, rate of change, thresholds, time-in-state, counting/timing, scheduling, grouping, probabilistic inference, smoothing, climate, domain conversion, decision matrix
template-guidelines	Confirming templates ARE appropriate for a use case; sharing Jinja logic between templates with custom_templates macros
yaml-only-integrations	Creating or editing YAML-only integrations that have no config flow (e.g. command_line, platform-based mqtt, rest)
device-control	Writing actions, button/remote automations, or using target:
scenes	Authoring or activating scenes; snapshot/restore patterns, including putting devices back the way they were after a temporary change; snapshot-vs-script distinction
dashboard-guide	Designing or modifying Lovelace dashboards — layout, view types, strategies, sections, cards, badges, CSS styling, HACS
dashboard-cards	Looking up built-in card types (core, energy, legacy) or where to read a card's fields
domain-docs	Looking up integration/domain documentation, or the dedicated doc page for a specific trigger, condition, or action
examples.yaml	Need compound examples combining multiple best practices
appdaemon	AppDaemon apps: when to use vs. native HA, app structure, actions, scheduling, error handling, safe refactoring impact
blueprint-guide	Authoring reusable blueprints: metadata & source_url, inputs & selectors, target vs entity, defaults, input sections, !input templating, versioning
backups	Deciding whether an operation needs a backup first; choosing between a full restore, a partial restore, and rolling one object back; what an archive actually contains; encryption keys and the emergency kit; restore verification; what HA does and does not protect when deleting a backup; whether a git config repo replaces a full backup