Pitfalls

These are cross-cutting Home Assistant platform gotchas — the ones that aren’t tied to a single topic. (Topic-specific pitfalls live on their own pages: integrations, Music Assistant, scripting, automations.) Each here is a short named trap and the fix.

Config precedence surprises

What bites you: the same thing is defined in two places — a UI-managed config and a file/package, say — and one silently overrides the other. You change the obvious one, nothing happens, and you lose an afternoon before finding the second definition quietly winning.

The fix: keep one authority per item (principles: one source of truth). Know which source wins for each kind of config, and don’t split a single concern across both. When behavior doesn’t match the config you just edited, suspect a second definition before anything else.

Deprecated vs current syntax

What bites you: you copy an example from an aging forum post and it doesn’t work, because the syntax changed. The classic is the old service: key versus the current action: key — but it’s a whole family of quietly-renamed options.

The fix: follow the current official docs, not search results sorted by what’s old enough to rank well. When an example fails for no obvious reason, check whether you’re looking at deprecated syntax.

Entity-id drift

What bites you: you rename or replace a device, its entity_id changes, and every automation, script, and dashboard referencing the old id silently breaks. Nothing errors loudly — things just stop working.

The fix: pin or alias entity_ids where you can, and after any device change, grep your config for the old id before you trust it. A two-minute search saves a confusing week.

Reload vs restart

What bites you: you reload the config, the change doesn’t take, and you assume your edit was wrong — when actually that kind of change needs a full restart, not a reload.

The fix: know which changes a reload covers and which need a restart. When a change “isn’t taking” and the config looks right, restart and re-verify before you go debugging a non-problem.

Reloading breaks open clients

What bites you: you reload after a deploy, then tap a control on a dashboard that was already open — and nothing happens. No error on screen, no log entry, and the script’s last-triggered timestamp never moves. It is indistinguishable from a broken automation, so you start debugging code that is fine.

The fix: make refreshing every open client the last step of the deploy, wall-mounted tablets first — they hold a session for days and nobody else will refresh them. And when a control “does nothing,” check the last-triggered timestamp before anything else: if it never moved, the action was never invoked and the problem is the client. Full treatment: deploys invalidate open clients.

Entity state can be arbitrarily stale

What bites you: you build logic on a source device’s state — “if the streaming box is off, the room is quiet” — and it is wrong for hours at a time. An integration reports what it last heard. CEC, native apps on the device, and physical remotes all change what a device is doing without telling Home Assistant, and nothing marks the state as old.

The fix: don’t treat a source entity’s state as ground truth. Ask the component that actually drives the speakers — the amplifier zone’s power and selected input — when the question is whether a room is in use, and treat the source entity as a hint. See stale state is not proof of silence.

Include / merge surprises

What bites you: directory-include and merge patterns combine files differently than you expect, or duplicate keys across files collide and one wins. The result is config that’s present but not behaving.

The fix: understand your include strategy (how files are merged, whether keys must be unique), and keep ids unique across included files. When in doubt, simplify the structure until the behavior is obvious.

Keep a per-device “do-not-retry” list

What bites you: a stubborn device accumulates a dozen dead ends — wrong input keys, a service that 500s, an API that doesn’t exist, a cloud path that’s flaky — and months later you (or your AI assistant) cheerfully re-test the same broken approaches because nobody wrote them down.

The fix: maintain a durable, dated list of what doesn’t work for each difficult device, alongside what does. It’s the single artifact that makes a stubborn device tractable, and it compounds: every dead end you record is days you never spend re-walking.

Power down sources before displays

What bites you: an “all off” that kills the displays first, then the source devices — and a streaming box’s CEC “active source” signal promptly wakes the displays right back up. The house won’t stay off.

The fix: order teardown upstream to downstream — sleep the source devices first (so nothing is left asserting “active source”), let it settle, then power off the displays last. The same CEC behavior that fights you in the wrong order is harmless in the right one.

Trust the management UI over the labels

What bites you: you automate an IP-controlled power outlet by the number on its sticker — and the management UI numbers them differently, so you reboot the wrong piece of core AV gear.

The fix: map each switched outlet to its real device through the controller’s own UI before automating power, and trust that mapping over the physical labels. Confirm by switching one outlet and watching what actually changes.

The one undocumented feed

What bites you: at cutover, a matrix input or a display goes dark because the old controller itself was quietly feeding it — content nobody had documented.

The fix: during discovery, hunt for any feed sourced by the legacy controller and decide its fate deliberately — migrate it or accept the loss on purpose — rather than discovering it the hard way. The power-off test is how you flush these out early.

See also