Troubliq

Smart-home fixes, step by step.

Category: General Troubleshooting

Cross-platform diagnostic methods, safe resets, backups, logs, updates, recovery, verification, escalation, and prevention.

  • Home Assistant Automation Triggered but Action Did Not Run: Trace the Failure

    Home Assistant Automation Triggered but Action Did Not Run: Trace the Failure

    When a Home Assistant automation appears to trigger but the light, switch, or other device does nothing, the problem is often downstream of the trigger: a condition evaluates to false, the wrong entity is targeted, an action fails, or the integration cannot deliver the command. Diagnose the run before rebuilding the automation.

    1. Confirm that the automation actually ran

    Open Settings → Automations & scenes, select the automation, and inspect its traces. Open the latest trace that matches the time you expected it to run. If there is no trace, check the trigger first: confirm the entity ID, trigger type, required state, and any time or numeric threshold. For a state trigger, remember that the entity must make the configured transition; already being in the target state may not create a new transition.

    Official reference: Home Assistant automation troubleshooting and traces.

    2. Find the first step that did not behave as expected

    • Trigger did not fire: verify the entity ID and the exact state or event in Developer Tools → States and the trace timeline.
    • Condition failed: inspect each condition’s actual values at the time of the run. A time condition, presence condition, or numeric-state condition can block an otherwise valid trigger.
    • Action was skipped: inspect Choose, If/then, Repeat, and Wait steps. A branch may not match, or a wait may time out.
    • Action ran but nothing changed: confirm the target entity and service/action, then test the action manually using the same target.

    3. Test the target separately

    Check that the target entity still exists and is available. An entity renamed during a device or integration change can leave an automation pointing at an old ID. If the action targets a group, area, script, or scene, test that target independently. Avoid deleting and recreating devices until you have confirmed the actual failure.

    4. Check execution mode and overlapping runs

    If an automation is still waiting or running, its mode can affect what happens when another trigger arrives. Review the automation’s mode and any delay, wait, or long-running action. Do not change the mode blindly: single, restart, queued, and parallel have different behavior and the right choice depends on the task.

    5. Use a safe minimal test

    1. Duplicate the automation or save a copy before making major changes.
    2. Temporarily simplify the test to one known trigger and one harmless action.
    3. Run the trigger and inspect the trace.
    4. Add the original conditions and actions back one at a time until the failure returns.

    This isolates the failing step instead of changing several settings at once. If the trace shows that the action completed but the device did not respond, investigate the device integration or network rather than rewriting the trigger.

    Related troubleshooting

    If the automation is not starting at all, see our guide to Home Assistant automations that do not run. If a device is unavailable, use our smart-light disconnection checklist before rebuilding automations.

    Quick checklist

    • Latest trace exists and matches the expected time.
    • Trigger and conditions show the expected values.
    • Target entity exists and is available.
    • Action succeeds when tested independently.
    • Execution mode and waits suit the automation.

    Bottom line: the trace usually tells you whether the failure is the trigger, a condition, a branch, or the action itself. Fix the first failing step and retest before making broader changes.

  • Smart Lights Keep Disconnecting: Wi-Fi, Zigbee, and Matter Checks

    Smart Lights Keep Disconnecting: Wi-Fi, Zigbee, and Matter Checks

    Smart lights that repeatedly go offline may have unstable power, weak wireless coverage, a mesh-routing problem, or a protocol-specific configuration issue. First identify how the bulb connects: Wi-Fi, Zigbee, Matter over Wi-Fi, or Matter over Thread. The correct fix depends on that connection.

    Connected smart-home lighting and devices
    Check the light and its network path before resetting it.

    1. Identify the protocol

    Check the product label, manual, and Home Assistant integration. A Wi-Fi bulb joins your wireless network directly. A Zigbee bulb communicates through a Zigbee coordinator and may rely on other powered Zigbee devices as routers. Matter is an application standard, not a radio by itself: Matter devices can use Wi-Fi or Thread. Thread devices need a working Thread border router and matching network credentials.

    2. Rule out power interruptions

    Make sure a wall switch, smart switch, or power strip is not cutting power to the bulb. A smart bulb generally needs continuous power to remain connected. If several lights in one fixture disconnect together, check the fixture, switch, and circuit before troubleshooting each bulb separately.

    3. Check Wi-Fi lights

    • Check signal strength where the bulb is installed, not beside the router.
    • Verify the bulb’s required Wi-Fi band, security mode, and router settings in its manual.
    • Look for router reboots, DHCP address problems, or access-point roaming events that match the outage.
    • If only distant bulbs fail, improve coverage rather than changing every network setting at once.

    Do not disable router security or split/change network settings blindly. Make one controlled change and test whether it improves stability.

    4. Check Zigbee mesh health

    Confirm the coordinator is online and inspect the device’s availability and link-quality information if your integration provides it. Compatible mains-powered Zigbee plugs and bulbs can route messages, but battery-powered sensors generally do not. Add or reposition routers gradually and allow time for the mesh to settle.

    Some bulbs do not behave well as routers for certain devices. If failures began after adding a new bulb or router, test that change instead of rebuilding the whole network.

    5. Check Matter over Thread

    Confirm the Thread border router is online and that Home Assistant has access to the intended Thread network. Do not assume a Zigbee coordinator extends Thread coverage; Zigbee and Thread use different mesh networks even though both may use 2.4 GHz radio.

    6. Use logs and timing

    Note whether lights disconnect after a router restart, at a certain time, or only when switched off at the wall. Compare that timing with Home Assistant logs, router logs, and integration availability events. Update firmware or integrations only when there is a relevant fix, and change one variable at a time.

    When to re-pair

    Re-pair only after power, coordinator, coverage, and compatibility checks. Before removing a device, record its name and the automations that use it; a replacement entity ID can break routines. If several devices fail simultaneously, troubleshoot the shared router, coordinator, or power source first. For broader diagnostics, use our smart-home device-unavailable decision guide and the Zigbee offline troubleshooting guide.

  • Home Assistant Cannot Find a New Zigbee Device: Step-by-Step Fixes

    Home Assistant Cannot Find a New Zigbee Device: Step-by-Step Fixes

    When a new Zigbee sensor, plug, or switch will not appear in Home Assistant, the cause is usually pairing mode, coordinator connectivity, radio interference, or device compatibility. Work through these checks in order and avoid resetting your entire Zigbee network as a first step.

    Smart-home device used during Zigbee pairing troubleshooting
    Use the device manufacturer’s pairing instructions for the exact model.

    1. Confirm which Zigbee integration is running

    Open Settings → Devices & services and identify whether your network is managed by Zigbee Home Automation (ZHA) or Zigbee2MQTT. Confirm the integration is loaded and its coordinator is available. A device cannot join if the coordinator or add-on is stopped, disconnected, or pointing to the wrong serial device.

    Use one Zigbee network for pairing. Do not try to join the same device through ZHA and Zigbee2MQTT simultaneously; they manage separate networks and coordinators.

    2. Start discovery before activating pairing

    Open the integration’s add-device flow first, then put the device into pairing mode exactly as the manufacturer specifies. Some devices advertise for only a short time. A battery device may need its button held or tapped in a specific sequence; avoid guessing, because reset patterns vary by model.

    3. Pair close to the coordinator

    For initial setup, place the device a few feet from the coordinator if practical. If the coordinator is a USB stick, use a USB extension cable to move it away from the computer, USB 3 ports, external drives, and Wi-Fi access point. Metal cabinets and dense walls can weaken radio communication.

    If close pairing works but the device fails in its final location, investigate coverage and mesh routing rather than repeating factory resets.

    4. Check compatibility and firmware

    Search the official ZHA device database or Zigbee2MQTT supported-device list for the exact model and hardware revision. Some devices need newer integration versions or specific firmware, and some expose only part of their features. Confirm the device uses Zigbee rather than Wi-Fi, Bluetooth, or Thread; similar-looking products can use different protocols.

    5. Read the logs before retrying

    Look at the integration logs at the time of the failed join. A timeout suggests a different problem from a serial-port error or an unsupported-device message. If the coordinator itself is unavailable, solve that first; repeated device resets will not fix a disconnected radio.

    6. Retry safely

    1. Confirm the coordinator is online.
    2. Enable permit-join or start the add-device flow.
    3. Reset only the target device using its manual.
    4. Pair near the coordinator and wait for discovery to finish.
    5. Move the device to its intended location and check signal quality.

    Delete a stale device entry only after confirming it belongs to the device you are repairing. Do not erase coordinator data or rebuild the network unless logs and backups support that decision.

    If it still will not pair

    Record the exact model, integration (ZHA or Zigbee2MQTT), coordinator model and firmware, Home Assistant version, and the relevant log message. Those details are far more useful than a general “device not found” report and help narrow down compatibility, radio, or configuration problems. For related cases, see our ZHA pairing checklist and Zigbee2MQTT interview-failure guide.

  • Home Assistant Devices Keep Going Offline: A Safe Troubleshooting Checklist

    Home Assistant Devices Keep Going Offline: A Safe Troubleshooting Checklist

    Smart home lighting and connected home devices
    Check the network path before resetting smart-home devices.

    If Home Assistant devices repeatedly become unavailable, do not start by deleting and re-pairing them. First find out whether the failure affects one device, one integration, an entire radio network, or Home Assistant itself. That distinction can save hours of rebuilding automations.

    1. Identify the scope of the outage

    • One device: check its battery, power, range, and recent physical changes.
    • Several devices on one protocol: inspect the Zigbee, Z-Wave, Thread, Wi-Fi, or Bluetooth network and its coordinator/router.
    • Devices from several integrations: check Home Assistant host health, network connectivity, and recent restarts.

    Record which entities are unavailable and when the problem began. Compare the timestamps rather than relying on memory.

    2. Check Home Assistant and the integration

    Open Settings → System → Repairs and review notifications. Then open the relevant integration and check whether it reports a setup or connection error. Review the log around the first failure; repeated errors after the outage may be symptoms, not the original cause.

    3. For Zigbee, check the coordinator and mesh

    This broad checklist helps identify which layer is failing; it is not a substitute for a protocol-specific recovery procedure. If the problem is specifically repeated Zigbee dropouts during normal use, follow the Zigbee dropout diagnosis. If the failure began immediately after power returned, use the power-outage recovery guide. Keep this page focused on identifying whether the issue is device-, protocol-, integration-, or host-wide.

    Confirm that the coordinator is powered and that the correct serial path is configured. If you use a USB radio, check whether a host restart changed device access or whether another process has taken control of the port. Powered Zigbee routers help extend the mesh; battery-powered sensors generally do not route traffic. After a power outage, give mains-powered routers time to rejoin before judging every sensor.

    4. For Wi-Fi devices, test the network first

    Check whether the device still appears in the router’s client list and whether its IP address changed. Review Wi-Fi signal, access-point restarts, DHCP reservations, and any recent network-name or password changes. Do not assign a static address inside the DHCP pool.

    5. Make one change at a time

    Restart only the affected integration when its logs point to an integration-level fault. Restarting the whole host can hide the evidence and interrupt unrelated devices. Avoid factory resets until power, connectivity, and integration setup have been checked.

    6. Verify the fix

    Watch the affected entity through several normal update cycles. Test the automation that depends on it, and check the log for fresh errors. If the device returns briefly and drops again, the underlying network or power problem may remain.

    Frequently asked questions

    Should I re-pair every unavailable device?

    No. Re-pair only when the device has genuinely lost its network membership or the integration’s documented recovery steps call for it.

    Why did everything go offline after a restart?

    Possible causes include a coordinator that did not reconnect, a changed device path, network startup timing, or an integration that failed to initialize. The logs and scope of the outage help separate them.

    What information helps diagnose the next step?

    Note the protocol, integration, device model, Home Assistant installation type, first error timestamp, and whether one device or many failed. Remove credentials and other private information before sharing logs.

    Image credit: Unsplash. This is a general troubleshooting guide; menu labels can vary by Home Assistant version and integration.

  • Home Assistant Says the Configuration Is Not Valid: Fix the First Error Safely

    Home Assistant Says the Configuration Is Not Valid: Fix the First Error Safely

    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

    1. Stop changing multiple files and note the last edit.
    2. Open Settings → Developer tools → YAML and run the configuration check. On Home Assistant OS or a supported CLI setup, use ha core check.
    3. Read the first specific file path, line number, integration name, or error message.
    4. Undo only the last risky change or restore the smallest known-good block.
    5. 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.

  • Home Assistant Says “This Entity Is No Longer Being Provided”: Diagnose Before Deleting

    Home Assistant Says “This Entity Is No Longer Being Provided”: Diagnose Before Deleting

    Direct answer: The warning “This entity is no longer being provided by the integration” means Home Assistant still has an entity-registry record, but the integration that created it did not create a matching live entity during the current startup or reload. Do not delete it immediately. First determine whether it is a truly retired entity, a renamed or duplicated replacement, an integration that failed to load, or—especially with MQTT—a discovery message that was not republished.

    Quick diagnostic box

    • One old entity, replacement works: update dashboards and automations, then remove the orphan only after verification.
    • Many entities from one integration: troubleshoot that integration before deleting anything.
    • MQTT or Zigbee2MQTT entities after a restart: verify broker connection and discovery/config messages.
    • New entity ends in _2: compare unique IDs and entity history before renaming or deleting.

    Safest first move: make a backup, record the old and new entity IDs, and check whether the integration is loaded. Deletion is cleanup—not a repair.

    What the warning actually tells you

    Home Assistant separates an entity’s saved registry record from the live entity object supplied by an integration. The registry keeps details such as the entity ID, unique ID, device association, name, and whether the entity was disabled. If the saved record exists but no current entity backs it, Home Assistant can show the record as no longer provided.

    This is different from an ordinary unavailable state. An unavailable entity may still be actively supplied by its integration even though the device or service cannot currently report a state. “No longer being provided” points to the relationship between the registry and the integration’s present setup.

    Ranked causes

    1. The integration renamed, replaced, or stopped creating the entity

    An update, device firmware change, configuration change, or integration migration can alter which entities are created. The old registry record remains because deleting it automatically could break dashboards, history references, scripts, scenes, and automations. A replacement may appear under a new entity ID or device entry.

    2. The integration failed to finish setup

    If several entities from the same integration show the warning at once, the problem is unlikely to be dozens of independent entity failures. Check Settings → Devices & services for setup, authentication, dependency, or communication errors. Then inspect logs from the time Home Assistant started or the integration was reloaded.

    3. MQTT discovery was not replayed

    MQTT-discovered entities require valid discovery configuration. Home Assistant’s MQTT documentation explains that after a restart, discovered items with a unique ID can remain unavailable until discovery messages are received again. Publishers commonly solve this with retained discovery configuration or by republishing configuration after Home Assistant’s birth message. An empty discovery payload can also remove a previously discovered device.

    Do not purge retained topics blindly. Retained messages can restore entities, but stale retained discovery can also recreate ghost entities. Identify the exact discovery topic and current payload first.

    4. The device or integration created a duplicate unique identity

    A replacement entity ending in _2 is a clue, not proof. Compare the integration, device, unique ID, state updates, and history. The working replacement may have been created because a device identifier, discovery topic, MAC address format, or integration entry changed. Renaming it prematurely can hide the evidence.

    5. The entity is disabled, deprecated, or intentionally removed

    Some integrations disable less-used entities by default, and integrations can retire entities when capabilities change. A disabled entity is not loaded into Home Assistant. Confirm whether the entity is marked disabled, deprecated, diagnostic-only, or no longer supported before treating it as broken.

    Safest diagnostic sequence

    Step 1: Preserve references

    Create a current Home Assistant backup. Record the warning, entity ID, integration, device, unique ID if visible, last-updated time, and any apparent replacement entity. Search dashboards, automations, scripts, scenes, templates, and helpers for the old entity ID. Do not expose tokens, passwords, broker credentials, network keys, or unredacted backups.

    Step 2: Decide whether the integration is healthy

    Open the integration page and check whether other entities from the same integration still update. If many fail together, stay at the integration layer: authentication, connectivity, configuration entry, dependency, or startup error. If only one registry record is affected while its siblings work, compare that entity with the device’s current capabilities and replacement entities.

    Step 3: Check the first meaningful log entry

    Restarting repeatedly can bury the useful evidence. Reproduce the problem once, note the time, and read the first related warning or error—not only later consequences. Separate setup failures, authentication failures, timeouts, invalid configuration, missing dependencies, and device-discovery changes.

    Step 4: For MQTT, prove the discovery path

    Confirm that the MQTT integration is connected to the intended broker. Verify that the publisher—such as Zigbee2MQTT or another bridge—is online and publishing current discovery configuration after Home Assistant starts. Compare the affected entity’s discovery topic and unique ID with a working entity. Do not publish test payloads to production topics unless you have a broker backup and understand the publisher’s discovery format.

    If your symptom began after a restart, also use the MQTT entities unavailable after restart guide. If the entity repeatedly changes between available and unavailable rather than showing “not provided,” use the MQTT availability flapping diagnostic.

    Step 5: Compare old and replacement entities

    Place the old and new entity IDs side by side. Confirm which one receives fresh states and controls the physical device. Compare device association, integration entry, unit, device class, and unique ID. Update one low-risk dashboard card first and verify it through a normal state change. Then update automations and templates carefully.

    If many duplicates appeared after an update, follow the duplicate-device repair guide before merging or deleting records.

    Step 6: Reload only when evidence supports it

    If the integration is otherwise healthy and supports reload, one controlled reload can show whether the entity is recreated. For an authentication problem, use Reauthenticate or Reconfigure where offered. Restart Home Assistant only when the logs or integration instructions justify it. Do not remove and re-add an entire integration to repair one orphaned record unless you have documented the downstream impact.

    When it is safe to delete the old entity

    Delete the registry record only when all of these are true:

    • the integration and device are healthy;
    • the old entity has a confirmed working replacement or is intentionally retired;
    • dashboards, automations, scripts, scenes, templates, and helpers no longer reference it;
    • you have preserved any history or identifier information you still need; and
    • a current backup exists.

    After deletion, restart only if the integration’s documentation calls for it. If the entity returns, the source is still advertising or creating it. That is evidence to inspect discovery or integration configuration—not a reason to delete it repeatedly.

    Verification checklist

    1. The integration loads without a repeating setup error.
    2. The intended entity receives a fresh state after a real device change.
    3. A harmless command works, when the entity is controllable.
    4. No automation or dashboard still points to the orphaned ID.
    5. The result survives an ordinary integration reload or planned Home Assistant restart.
    6. No duplicate device or _2 entity reappears.

    Prevention

    • Back up before Home Assistant, integration, broker, or bridge migrations.
    • Document entity IDs used by critical automations.
    • For MQTT publishers, follow Home Assistant’s discovery, birth-message, and retained-message guidance.
    • Change one identity-related setting at a time and verify after each change.
    • Review release notes before updates that migrate device or entity registries.

    FAQ

    Is “not provided” the same as “unavailable”?

    No. Unavailable can mean a live entity cannot currently obtain a state. “No longer being provided” means the saved registry entry is not backed by a live entity from its integration.

    Will deleting the entity fix the integration?

    No. Deletion removes the orphaned registry record. It does not repair authentication, MQTT discovery, a failed setup, or device connectivity.

    Why did a second entity appear with _2?

    Home Assistant encountered an entity-ID collision or a new unique identity. Compare old and new records before renaming either one.

    Should I remove and re-add the integration?

    Usually not as a first step. Re-adding can change identifiers and break references. Diagnose setup, authentication, discovery, and replacement entities first.

    Primary sources

    Reviewed against official documentation on September 30, 2026.

  • Home Assistant Automation Runs Twice: Trace Duplicate Triggers Without Guessing

    Home Assistant Automation Runs Twice: Trace Duplicate Triggers Without Guessing

    Direct answer: When a Home Assistant automation runs twice, do not add a delay or change its run mode first. Open two traces and compare the trigger description, trigger ID, timestamp and action path. Most duplicate-looking runs come from two valid triggers, a state trigger that matches more transitions than intended, the same automation loaded twice, an event emitted twice by the source integration, or two different automations calling the same action. The trace evidence tells you which branch to fix.

    Quick diagnostic box

    • Time: about 15 minutes if traces exist.
    • Risk: low when you inspect first and change one automation at a time.
    • Start here: open Settings → Automations & scenes, select the automation, open Traces, and compare the two runs.
    • Preserve evidence: record both timestamps, trigger descriptions, trigger IDs, run IDs and the action that appeared twice.
    • Do not delete the automation, add a random delay, or switch to mode: single before you identify whether there were actually two triggers.

    First decide what “twice” means

    Two notifications, two light commands or two logbook entries do not necessarily prove that one automation ran twice. A single run can call the same action from two branches, a script can repeat an action, a device can report the same change twice, and two separate automations can target the same service. Conversely, one automation can legitimately start two runs milliseconds apart.

    Use traces as the source of truth. If there are two trace entries with different run IDs, Home Assistant started the automation twice. If there is one trace with two action calls, the duplication is inside the action sequence, script or downstream integration. If there is only one action call but the device responds twice, investigate the target integration or device rather than the automation trigger.

    Preserve the evidence before reloading

    Home Assistant stores a limited number of traces by default. A reload or edit can make the original state harder to reconstruct. Open both traces and note the exact time, trigger, changed entity, from/to values and path through conditions and choose blocks. Export or copy only the minimum sanitized details required. Remove tokens, webhook IDs, personal locations, device serials, public URLs and notification contents.

    For YAML automations, Home Assistant documentation allows the number of stored traces to be increased with the trace stored_traces option. Do this only when the problem is intermittent and existing traces are being overwritten; it does not repair duplicate execution.

    Ranked cause 1: two triggers are both valid

    Multiple triggers in one automation are evaluated independently. If a motion sensor changes state and a related helper or template changes moments later, both may start the automation. Time, sun, state and event triggers can also overlap at a boundary. Give each trigger a unique ID and compare trigger.id in the trace. The IDs turn an ambiguous duplicate into a measurable pattern.

    triggers:
      - trigger: state
        entity_id: binary_sensor.kitchen_motion
        to: "on"
        id: motion_started
      - trigger: state
        entity_id: input_boolean.kitchen_override
        to: "on"
        id: override_started

    If either trigger is sufficient, two runs may be correct. Prevent the duplicate at the logic level: choose one source of truth, add a condition that excludes the overlapping case, or branch by trigger ID so both triggers do not execute the same action. Do not use a blanket delay as a substitute for understanding the overlap.

    Ranked cause 2: a state trigger matches more transitions than intended

    A state trigger without a to or from filter can fire when the entity changes state and, depending on the entity and configuration, attribute changes may also matter. A template trigger can become true again after briefly returning false. Numeric thresholds trigger when crossing the boundary, not continuously, but noisy measurements can cross back and forth.

    In each trace, inspect from_state and to_state. If the meaningful state is identical but an attribute changed, narrow the trigger. If the state bounced off and on, fix the noisy source if possible or use a documented duration only when the desired behavior truly requires the state to remain stable. Remember that Home Assistant’s for option does not survive an automation reload or Home Assistant restart.

    Ranked cause 3: the same automation is loaded twice

    This occurs when equivalent logic exists in the UI and YAML, when an automation was copied and renamed, or when an include causes the same file to be referenced unexpectedly. Search the automation list for the target entity, notification text or distinctive alias. In YAML, confirm that each automation has a unique ID and that automations.yaml remains a list.

    Do not remove files blindly. Disable one suspected duplicate, trigger the original condition once, then review traces. If the second run disappears, document which definition remains authoritative before deleting or consolidating anything.

    Ranked cause 4: two automations call the same script or service

    A duplicated outcome may come from different parents. Search for the service call, script entity, scene, notification message or target entity across automations and scripts. A script trace can show two callers even when each parent automation ran only once. The clean repair is usually to consolidate the shared decision into one automation or make the script idempotent where practical.

    Idempotent means a repeated request leaves the system in the same safe state. Turning a light on is often naturally idempotent; sending a notification, incrementing a counter, unlocking a door or making an API request may not be. High-impact actions deserve explicit guards and verification.

    Ranked cause 5: the source integration emits two events

    Some devices expose both a state change and an event. A button integration may create a device trigger plus an event trigger for the same press. MQTT can deliver retained or repeated messages depending on publisher behavior and quality-of-service configuration. Mobile apps, webhooks and cloud integrations can retry requests.

    Compare event data and timestamps in the traces. If the automation received two genuinely separate source events, the trigger is behaving as configured. Correct the publisher when possible. If correction is impossible, use a narrow guard based on a stable event identifier or a short helper-based deduplication window that matches the source behavior. Document the tradeoff: any deduplication rule can suppress legitimate rapid actions.

    Ranked cause 6: actions repeat inside one run

    Open the trace timeline and count action nodes. Check repeat blocks, parallel sequences, choose branches, scripts and wait/restart paths. A common mistake is to place the same service call before and after a choose block, or to call a script directly and again through a scene or another script.

    Fix the duplicated branch rather than changing trigger behavior. Retest the automation manually only after confirming that manual execution is safe; the Run actions control skips normal trigger timing and can make destructive or noisy actions happen immediately.

    Why automation mode is not the first fix

    Home Assistant modes control what happens when a new run starts while another is active. Single rejects a new overlapping run; restart stops the old run and starts the new one; queued waits; parallel allows independent runs. A mode can change the visible symptom, but it does not explain why two triggers occurred.

    If an automation finishes in 100 milliseconds and the second trigger arrives later, mode single will not block it. If you switch to restart, the first run may be interrupted halfway. If you use queued, both unwanted runs may still execute. Select mode based on the intended concurrency after fixing trigger logic.

    A privacy-safe trace comparison

    Run A
    time: 2026-09-29 18:42:10.218
    trigger_id: motion_started
    entity: binary_sensor.room_motion
    from: "off"
    to: "on"
    action_path: choose/0/sequence/0
    
    Run B
    time: 2026-09-29 18:42:10.463
    trigger_id: occupancy_started
    entity: binary_sensor.room_occupancy
    from: "off"
    to: "on"
    action_path: choose/0/sequence/0

    This sanitized example shows two independent triggers reaching the same action 245 milliseconds apart. The evidence points to overlapping motion and occupancy logic, not a Home Assistant scheduler that randomly duplicated one run. Replace real entity names and timestamps when sharing logs publicly.

    Common duplicate-run patterns

    At Home Assistant startup: An automation may have a Home Assistant start trigger while the same entities also restore or update their state. Compare trigger IDs. If both paths are intentional, decide whether startup should initialize state silently or perform the normal outward action. Avoid sending duplicate alerts simply because several entities become available together.

    At sunrise, sunset or a scheduled minute: A time trigger can overlap with a sun, schedule or template trigger that becomes true at nearly the same moment. Use one clock source for the action or branch explicitly so the fallback does not duplicate the primary trigger.

    After an automation reload: Reloading attaches the current trigger definitions. It should not be treated as a routine cure for duplicates. If behavior changes only after reload, inspect whether YAML and UI definitions differ, whether a custom integration registers listeners correctly, and whether the issue returns after the next edit or restart.

    After reconnecting MQTT or another event source: A retained message, restored entity state or publisher retry can reproduce an apparently old condition. Compare message payloads and source timestamps rather than assuming the automation engine replayed a run. Do not delete retained messages globally; identify the topic and publisher first.

    Only when actions take a long time: This pattern makes concurrency mode relevant. If a second trigger arrives while the first sequence is waiting, mode parallel may create two active paths, queued may preserve both, restart may abandon the first, and single may reject the second. Choose the mode that matches the intended physical behavior and include timeouts for waits that could otherwise remain open.

    Do not create a fragile cooldown

    A cooldown helper can be appropriate for a genuinely noisy source, but it must have a defined duration and consequence. A five-second lockout that hides a duplicate door event could also suppress a real reopen. Before adding one, measure the duplicate interval from traces, decide the fastest legitimate repeat, and choose a guard narrower than that legitimate behavior.

    For notifications, consider whether the message can be keyed to an event ID or state transition. For counters and paid API calls, verify that a repeated request cannot create financial or operational harm. For locks, covers, garage doors and alarms, prefer fixing the source and adding explicit safety conditions over relying on a timer.

    Safest repair sequence

    • Create a current backup before editing important automations.
    • Capture the two traces and identify whether there are two runs or one run with two actions.
    • Assign trigger IDs if the automation has multiple triggers.
    • Narrow state triggers with explicit to/from values where that matches the intent.
    • Search for duplicate automations and other parents calling the same script or service.
    • Change one cause only. Reload automations if you edited YAML; do not restart the whole host unless required.
    • Trigger one controlled test and inspect the new trace.
    • Test again after the source has been idle long enough to reproduce the original condition.
    • Verify the physical outcome, notification count and Logbook entry.
    • Record the final change and keep the evidence until the behavior remains stable.

    Verification matrix

    • Two traces, different trigger IDs: overlapping triggers; fix conditions or choose a source of truth.
    • Two traces, same trigger ID: inspect bouncing state, repeated events, duplicate definitions or publisher retries.
    • One trace, two action nodes: repair the action sequence, choose/repeat block or child script.
    • One trace, one action call, device acts twice: investigate the integration, transport or device.
    • No trace for one outcome: another automation, integration or external platform probably caused it.

    Prevention

    Name automations and scripts for the outcome they own. Use unique IDs, assign trigger IDs, avoid duplicating the same decision across UI and YAML, and keep high-impact actions centralized. Store enough traces to cover the diagnostic window without retaining unnecessary sensitive details. After Home Assistant or integration updates, test automations that send messages, unlock doors, operate covers, change climate settings or call paid APIs.

    Use the automation-not-triggering guide when the opposite failure occurs. Sanitize evidence with the Troubliq Log Sanitizer, and use the Error Decoder for an exact message or warning.

    When to escalate

    Escalate when two traces show one integration producing reproducible duplicate events, when the trace data contradicts the documented mode behavior, or when duplication began immediately after a known update and persists in a minimal test. Include Home Assistant Core version, installation type, sanitized automation YAML, two traces, relevant integration version and the smallest reproduction. Do not publish secrets or an entire configuration archive.

    Official sources and review record

    Last reviewed September 29, 2026. Photo credit: Luke Chesser via Unsplash.

  • HomeKit Bridge Accessories Disappear After Adding More Devices in Home Assistant

    HomeKit Bridge Accessories Disappear After Adding More Devices in Home Assistant

    When older accessories disappear after new Home Assistant entities are exposed to Apple Home, the bridge may be overloaded, filtered differently, or represented by a changed configuration. The safest repair is to reduce and stabilize the bridge rather than repeatedly deleting it from both systems.

    What this failure pattern tells you

    This guide uses a narrow diagnostic sequence: confirm the pattern, protect the current configuration, test the smallest likely cause, and verify the result before moving deeper. That approach avoids turning one failed device or automation into a site-wide recovery job.

    • Some accessories vanish while the HomeKit Bridge integration remains loaded.
    • The issue appears after exposing a large room, domain, or group of entities.
    • Home shows ‘No Response’ for a subset of accessories.
    • Re-pairing temporarily restores devices but the problem returns.

    Most likely causes

    • Too many accessories or services are exposed through one bridge.
    • Include/exclude filters changed after an entity rename.
    • Unsupported or unusually complex entities create excessive services.
    • The bridge’s pairing state and Apple Home cache no longer agree.
    • Network isolation blocks mDNS between Home Assistant and Apple hubs.

    Before changing anything

    Make a current Home Assistant backup and download it somewhere outside the system. Take screenshots of the affected integration, device, entity IDs, and any relevant automation. Record the exact time of the next failure so the log window stays small. If the issue involves radio hardware, do not unplug it while Home Assistant is writing data.

    Step-by-step diagnosis and repair

    1. Create a Home Assistant backup and capture the current HomeKit Bridge include/exclude configuration.
    2. Count exposed entities and identify high-service devices such as multi-sensors, media players, or complex climate entities.
    3. Temporarily narrow one bridge to a small, essential set using explicit includes.
    4. Reload the integration and wait before making another change; Apple Home synchronization is not always immediate.
    5. Confirm Home Assistant, the iPhone, and the active Apple home hub can exchange local mDNS traffic across VLANs.
    6. If the smaller bridge is stable, divide devices logically across multiple bridges rather than placing everything on one.
    7. Only as a final step, remove one confirmed broken bridge pairing and re-pair it using the new stable scope. Expect room assignments and automations to require review.

    How to verify the repair

    Do not declare success immediately after a reload. Repeat the original action several times, then observe the system through at least one normal restart or reconnect cycle. Review the log at the exact test time and confirm that the affected entities update normally. If the problem was intermittent, keep a short note of the previous failure interval and monitor beyond it.

    Common mistakes to avoid

    • Do not delete every bridge simultaneously.
    • Do not expose entire domains when only a few entities are useful.
    • Do not keep changing filters during Apple Home synchronization.

    A practical decision rule

    If several unrelated devices fail at the same moment, investigate shared infrastructure: power, network, broker, radio, host load, or a recent update. If only one model or entity fails while everything around it remains stable, focus on that device’s identity, firmware, configuration, and signal path. Rebuilding a healthy shared integration should be the final option, not the first.

    When to restore a backup

    Restore only when you can identify a known-good backup from before a harmful configuration change and you understand what newer changes will be lost. A backup is not a substitute for diagnosing failing hardware, interference, duplicate identifiers, or unstable power; those problems will return after restoration.

    Frequently asked questions

    Should I use one bridge or several?

    Several smaller, logically grouped bridges are often easier to diagnose and keep within practical accessory and service limits.

    Will re-pairing preserve Apple Home rooms?

    Not reliably. Treat re-pairing as a last resort and document room and automation assignments first.

    Why do VLANs matter?

    HomeKit discovery relies heavily on local multicast discovery, which routed or isolated networks may block.

    Bottom line

    Start with evidence from the affected device, integration, trace, or topic. Protect the working system, change one variable, and verify through the original failure condition. That is slower than random resets for five minutes and much faster than rebuilding an entire smart home unnecessarily.

    Deep diagnostic worksheet

    Use this worksheet when the quick repair does not hold. The objective is to build a timestamped explanation of the HomeKit Bridge accessory loss problem rather than accumulate unrelated changes. Keep credentials and private addresses out of screenshots or public reports.

    1. Count accessories exposed through each bridge and record the filter configuration. Home Assistant’s official documentation notes a maximum of 150 unique accessories per bridge.
    2. Identify whether missing items share a domain, room, integration, or recent rename. A filter mismatch often removes a group predictably rather than at random.
    3. Record bridge names, pairing state, Apple home hub status, and the last configuration change. Avoid deleting pairings while collecting evidence because re-pairing can disturb room assignments.
    4. Confirm Home Assistant, the phone, and the active Apple home hub can exchange local multicast discovery traffic. Guest Wi-Fi, VLAN isolation, or multicast filtering can break discovery.
    5. Reduce one test bridge to a small explicit include list. This separates bridge-size and entity-complexity problems from general network failure.
    6. Review unsupported or unusually complex entities. One physical Home Assistant device can expose multiple HomeKit services, so entity count alone may not describe bridge complexity.
    7. Wait after reloading a bridge and make one change at a time. Apple Home synchronization and hub caching can make rapid edits appear inconsistent.
    8. Document Apple Home automations and room assignments before any final re-pair, because removing and adding a bridge may require rebuilding organization.

    Failure-pattern examples

    • Accessory count approaches 150: split devices into logical bridges before adding more and keep explicit filters.
    • Only renamed entities disappear: update include/exclude filters and reload the affected bridge, then allow synchronization time.
    • Everything shows No Response after a network change: investigate mDNS routing, VLAN rules, Wi-Fi isolation, and active home-hub connectivity.
    • A small test bridge works but the large bridge fails: reduce scope and separate complex domains rather than repeatedly re-pairing the same oversized bridge.
    • One bridge is healthy and another is not: isolate configuration and pairing work to the failing bridge; do not delete every HomeKit integration.

    Advanced notes that prevent false fixes

    • The 150-accessory limit applies per bridge, and service complexity can create practical issues before the numeric limit.
    • Explicit include lists are easier to audit than exposing entire domains by default.
    • Cameras and other complex accessories may deserve separate planning because their requirements differ from simple switches.
    • Network changes can mimic configuration failures; prove local discovery works before rebuilding pairings.
    • Re-pairing is destructive to organization even when it fixes connectivity, so it belongs late in the decision tree.
    • Maintain a bridge inventory containing purpose, included entities, approximate accessory count, pairing date, and responsible Apple home.

    Final verification checklist

    Verification must reproduce the original condition. A page reload or one successful command is insufficient for an intermittent problem.

    • Every intended accessory appears once.
    • The bridge remains responsive through a home-hub change or normal restart.
    • Accessory count stays below the documented limit.
    • Room assignments and automations remain intact.
    • No unintended entity domain is exposed.
    • The result remains stable after synchronization time.

    Official reference

    Technical behavior and terminology were checked against Home Assistant HomeKit Bridge documentation. Interface labels and capabilities can change, so use the current official page when your installed version differs.

    Related Troubliq guides

  • MQTT Device Flaps Between Available and Unavailable in Home Assistant

    MQTT Device Flaps Between Available and Unavailable in Home Assistant

    An MQTT entity that changes from available to unavailable every few minutes may still publish sensor values correctly. The useful clue is the availability topic: Home Assistant is reporting what it receives, not guessing whether the physical device is healthy.

    What this failure pattern tells you

    This guide uses a narrow diagnostic sequence: confirm the pattern, protect the current configuration, test the smallest likely cause, and verify the result before moving deeper. That approach avoids turning one failed device or automation into a site-wide recovery job.

    • State values update, but the device badge repeatedly becomes unavailable.
    • The problem begins after broker, router, or Home Assistant restarts.
    • Several devices fail together, or only one firmware family is affected.
    • The log shows reconnects, socket errors, or duplicate client identifiers.

    Most likely causes

    • A retained offline payload remains on the availability topic.
    • The device uses a short keepalive and unstable Wi-Fi.
    • Two clients share the same MQTT client ID and disconnect each other.
    • Birth and Last Will payloads do not match Home Assistant’s expected values.
    • The broker, add-on, or device clock restarts on a repeating schedule.

    Before changing anything

    Make a current Home Assistant backup and download it somewhere outside the system. Take screenshots of the affected integration, device, entity IDs, and any relevant automation. Record the exact time of the next failure so the log window stays small. If the issue involves radio hardware, do not unplug it while Home Assistant is writing data.

    Step-by-step diagnosis and repair

    1. Open the MQTT integration and listen to the exact availability topic; record payloads and timestamps without publishing anything.
    2. Compare the entity’s configured payload_available and payload_not_available values, including capitalization and whitespace.
    3. Check whether the offline message is retained. A stale retained Last Will can survive restarts.
    4. Inspect the broker log for repeated connections using the same client ID.
    5. Give every physical device a unique client ID, then restart only the affected client.
    6. Check Wi-Fi signal, DHCP stability, power supply, and keepalive settings on the device.
    7. If multiple devices fail simultaneously, investigate broker or network infrastructure before editing every device.
    8. After correcting the publisher, clear or replace only the known stale retained availability message using the device’s documented procedure.

    How to verify the repair

    Do not declare success immediately after a reload. Repeat the original action several times, then observe the system through at least one normal restart or reconnect cycle. Review the log at the exact test time and confirm that the affected entities update normally. If the problem was intermittent, keep a short note of the previous failure interval and monitor beyond it.

    Common mistakes to avoid

    • Do not publish a blank retained payload to broad wildcard topics.
    • Do not disable availability reporting just to hide a real disconnect.
    • Do not expose the broker to the public internet while troubleshooting.

    A practical decision rule

    If several unrelated devices fail at the same moment, investigate shared infrastructure: power, network, broker, radio, host load, or a recent update. If only one model or entity fails while everything around it remains stable, focus on that device’s identity, firmware, configuration, and signal path. Rebuilding a healthy shared integration should be the final option, not the first.

    When to restore a backup

    Restore only when you can identify a known-good backup from before a harmful configuration change and you understand what newer changes will be lost. A backup is not a substitute for diagnosing failing hardware, interference, duplicate identifiers, or unstable power; those problems will return after restoration.

    Frequently asked questions

    Can sensor values update while availability is wrong?

    Yes. State and availability often use different topics and retained-message behavior.

    What does a duplicate client ID do?

    Most brokers disconnect the older session when another client connects with the same identifier, creating a repeating online/offline cycle.

    Should I delete the MQTT integration?

    Usually not. First isolate the exact topic, payload, client ID, and timestamp pattern.

    Bottom line

    Start with evidence from the affected device, integration, trace, or topic. Protect the working system, change one variable, and verify through the original failure condition. That is slower than random resets for five minutes and much faster than rebuilding an entire smart home unnecessarily.

    Deep diagnostic worksheet

    Use this worksheet when the quick repair does not hold. The objective is to build a timestamped explanation of the MQTT availability problem rather than accumulate unrelated changes. Keep credentials and private addresses out of screenshots or public reports.

    1. Capture the exact availability topic and every payload over a complete online-offline cycle. Include timestamps, retain flags when available, and client connection events from the broker log.
    2. Compare the observed strings byte-for-byte with payload_available and payload_not_available. Capitalization, whitespace, encoding, and JSON structure matter; visually similar payloads may not match.
    3. Determine whether the entity uses one availability topic or a list. Home Assistant supports availability modes such as all, any, and latest, and the selected mode changes how multiple topics are evaluated.
    4. Inspect broker logs for duplicate client identifiers. MQTT brokers commonly replace an existing connection when a second client connects with the same ID, producing a repeating disconnect pattern.
    5. Check the device’s Last Will, birth message, retain setting, keepalive, and clean-session behavior. Availability faults often survive restarts because a retained offline payload remains valid at the broker.
    6. Correlate failures across devices. Simultaneous changes point toward broker, network, power, DNS, or host problems; one device family points toward its firmware or configuration.
    7. Measure Wi-Fi signal and power stability at the device, but do not stop there. A strong signal does not rule out DHCP conflicts, access-point roaming, brownouts, or duplicate credentials.
    8. Before clearing a retained message, verify the exact topic and understand the publishing tool. A wildcard or wrong topic can disturb many devices.

    Failure-pattern examples

    • State updates continue while availability is offline: troubleshoot the availability topic and payload separately from the state topic.
    • All MQTT devices go unavailable after a broker restart: inspect retained birth/Last Will behavior and reconnection logs before editing every entity.
    • One device flips at a fixed interval: compare keepalive, watchdog, DHCP lease, power-save, and scheduled restart timing.
    • Two identical devices knock each other offline: assign unique MQTT client IDs and confirm both remain connected simultaneously.
    • Multiple availability topics use mode all: one silent auxiliary topic can hold the entity offline even though the primary device is publishing normally.

    Advanced notes that prevent false fixes

    • Retained messages describe the last retained value, not necessarily the present physical state; publishers must update them correctly.
    • QoS affects delivery guarantees but does not repair a semantically wrong availability payload.
    • Disabling availability hides the diagnostic signal and should not substitute for fixing reconnections.
    • Do not expose an MQTT broker publicly or weaken authentication during troubleshooting.
    • Use a narrow topic listener and redact usernames, passwords, tokens, and personally identifying topic components.
    • After repair, document topic names, expected payloads, client ID, retain behavior, and broker location.

    Final verification checklist

    Verification must reproduce the original condition. A page reload or one successful command is insufficient for an intermittent problem.

    • The client remains connected longer than the previous failure interval.
    • Availability and state topics show expected payloads.
    • No duplicate-client disconnect appears in broker logs.
    • The entity recovers correctly after one controlled broker restart.
    • Other MQTT devices remain unaffected.
    • No stale retained offline value reappears.

    Official reference

    Technical behavior and terminology were checked against Home Assistant MQTT documentation. Interface labels and capabilities can change, so use the current official page when your installed version differs.

    Related Troubliq guides

  • ESPHome Device Shows Two Entries in Home Assistant: Remove the Duplicate Safely

    ESPHome Device Shows Two Entries in Home Assistant: Remove the Duplicate Safely

    Duplicate ESPHome entries commonly appear after a device name change, board replacement, restored backup, or re-adoption. One entry may use the native API while another is a stale registry record. Deleting both entries can turn a cosmetic problem into an outage, so identify which connection is live first.

    What this failure pattern tells you

    This guide uses a narrow diagnostic sequence: confirm the pattern, protect the current configuration, test the smallest likely cause, and verify the result before moving deeper. That approach avoids turning one failed device or automation into a site-wide recovery job.

    • Two devices have similar names but different entity counts.
    • One copy is unavailable while the other updates normally.
    • Automations reference entities from both entries.
    • A renamed node keeps its old device or entities.

    Most likely causes

    • The ESPHome node name or friendly name changed.
    • A replacement board reused some identifiers but not the original API identity.
    • An old integration entry survived a reinstall or restore.
    • Entities were disabled or renamed, making the working copy difficult to recognize.
    • mDNS discovery found a node that had also been added manually.

    Before changing anything

    Make a current Home Assistant backup and download it somewhere outside the system. Take screenshots of the affected integration, device, entity IDs, and any relevant automation. Record the exact time of the next failure so the log window stays small. If the issue involves radio hardware, do not unplug it while Home Assistant is writing data.

    Step-by-step diagnosis and repair

    1. Open both device pages and record the integration entry, IP address, last-updated behavior, and entity IDs.
    2. Trigger a harmless physical change such as toggling an onboard LED or watching a sensor update; identify the entry receiving fresh state.
    3. Open automations, scripts, dashboards, and scenes that use the stale entity IDs and move them to the live entities before removal.
    4. Create a backup and export or copy the working ESPHome YAML.
    5. Remove only the unavailable integration entry from Settings → Devices & services. Do not delete the working node from the ESPHome dashboard.
    6. Restart Home Assistant once and allow discovery to settle.
    7. If the duplicate returns, compare the node name, API encryption key, static IP, and manual integration host. Keep one consistent discovery method.
    8. Rename entities for clarity only after the device registry is stable.

    How to verify the repair

    Do not declare success immediately after a reload. Repeat the original action several times, then observe the system through at least one normal restart or reconnect cycle. Review the log at the exact test time and confirm that the affected entities update normally. If the problem was intermittent, keep a short note of the previous failure interval and monitor beyond it.

    Common mistakes to avoid

    • Do not wipe the board merely to clean the registry.
    • Do not delete both integrations at once.
    • Do not reuse the same node name for two powered devices on the same network.

    A practical decision rule

    If several unrelated devices fail at the same moment, investigate shared infrastructure: power, network, broker, radio, host load, or a recent update. If only one model or entity fails while everything around it remains stable, focus on that device’s identity, firmware, configuration, and signal path. Rebuilding a healthy shared integration should be the final option, not the first.

    When to restore a backup

    Restore only when you can identify a known-good backup from before a harmful configuration change and you understand what newer changes will be lost. A backup is not a substitute for diagnosing failing hardware, interference, duplicate identifiers, or unstable power; those problems will return after restoration.

    Frequently asked questions

    Will removing the stale entry erase the ESPHome firmware?

    No. Removing an integration entry from Home Assistant does not normally erase firmware from the microcontroller.

    Why did the duplicate return?

    The device may still advertise a different identity, or a manual host entry may coexist with automatic discovery.

    What should I back up?

    The ESPHome YAML, secrets references, API encryption key, and any automation entity mappings.

    Bottom line

    Start with evidence from the affected device, integration, trace, or topic. Protect the working system, change one variable, and verify through the original failure condition. That is slower than random resets for five minutes and much faster than rebuilding an entire smart home unnecessarily.

    Deep diagnostic worksheet

    Use this worksheet when the quick repair does not hold. The objective is to build a timestamped explanation of the duplicate ESPHome entry problem rather than accumulate unrelated changes. Keep credentials and private addresses out of screenshots or public reports.

    1. Write down both device IDs, integration-entry names, host addresses, entity counts, and last-updated times before deleting anything. Similar display names do not prove that two records represent the same API identity.
    2. Trigger a harmless live change and watch which entity updates. The responding entry is the operational record; an unavailable copy may be stale, but automation references must still be migrated before removal.
    3. Open the ESPHome YAML and record the node name, friendly name, API encryption configuration, Wi-Fi addressing, and any name_add_mac_suffix behavior. Identity changes can produce new discovery records.
    4. Search Home Assistant automations, scripts, scenes, dashboards, and helpers for entity IDs belonging to both copies. A clean device list is not useful if hidden references break afterward.
    5. Compare manual integration configuration with automatic mDNS discovery. A manually added IP plus a separately discovered identity can look like duplication even when only one board exists.
    6. Confirm that two physical boards are not using the same node name or static IP. Power one board at a time if necessary and observe which record changes availability.
    7. If the board was replaced, decide deliberately whether the new device should inherit the old logical role. Rename and remap entities after connectivity is stable, not during discovery troubleshooting.
    8. Back up the YAML, secrets reference, encryption key, and automation mappings. Removing a Home Assistant integration entry normally does not erase firmware, but losing configuration still creates recovery work.

    Failure-pattern examples

    • Old entry unavailable, new entry healthy after a rename: migrate every reference to the new entities, verify automations, then remove only the stale integration entry.
    • Two entries alternate availability: check duplicate IP addresses, duplicate node names, cloned firmware, and whether two boards share credentials or network identity.
    • Duplicate returns after deletion: identify the discovery advertisement and any manual host entry. Do not keep deleting the symptom while the device continues advertising a second identity.
    • Replacement board should assume the old role: preserve a clear mapping of entity IDs and update consumers methodically; do not expect identical registry identity automatically.
    • mDNS is disabled or blocked: follow ESPHome guidance by using stable addressing and a deliberate manual integration rather than relying on discovery that cannot traverse the network.

    Advanced notes that prevent false fixes

    • The node name affects hostname and discovery, while the friendly name mainly affects presentation; changing them has different consequences.
    • API encryption keys must match between firmware and Home Assistant. A mismatch is a connection problem, not evidence that the registry should be erased.
    • Disabled entities can make two entries look different, so compare full entity lists rather than only dashboard cards.
    • Entity IDs are user-facing references; device and config-entry identifiers are separate registry layers.
    • Restoring an old Home Assistant backup while devices run newer identities can reintroduce stale registry records.
    • Document the final node name, IP strategy, encryption-key storage, and entity mapping after cleanup.

    Final verification checklist

    Verification must reproduce the original condition. A page reload or one successful command is insufficient for an intermittent problem.

    • Only one intended integration entry remains.
    • The live device reconnects after a normal restart.
    • Every automation and dashboard uses current entity IDs.
    • No duplicate IP or hostname exists on the LAN.
    • Encryption works without repeated authentication errors.
    • The duplicate does not return after the next discovery cycle.

    Official reference

    Technical behavior and terminology were checked against ESPHome Native API documentation. Interface labels and capabilities can change, so use the current official page when your installed version differs.

    Related Troubliq guides