Troubliq

Smart-home fixes, step by step.

Blog

  • Home Assistant backup asks for an encryption key: find the emergency kit and restore safely

    Home Assistant backup asks for an encryption key: find the emergency kit and restore safely

    Direct answer: If Home Assistant asks for an encryption key during restore, the backup is encrypted and must be unlocked with the matching key from its backup emergency kit. The key is not your Home Assistant login password, cloud password, or device PIN. If the original Home Assistant installation still works, open its backup settings and download the emergency kit again before doing anything destructive. If the old installation is unavailable, search the safe locations where you stored the kit and check any supported cloud backup account. Do not overwrite the old system or delete backup files while searching.

    Symptoms and scope

    • A backup uploads successfully but restore requests an encryption key.
    • Your normal Home Assistant password is rejected.
    • A migration stops because you cannot find the emergency kit.
    • An automatic backup exists in cloud or network storage, but you cannot decrypt it.
    • You have several emergency kits and do not know which matches the backup.
    • A restore begins but fails because the file is incomplete, damaged, or from an incompatible environment.

    This guide applies to Home Assistant’s current encrypted backup system introduced with the backup overhaul in 2025. It covers the safe decision process around finding the key, verifying the backup, and restoring. It does not provide a method to bypass encryption; strong backup encryption is specifically intended to prevent that.

    What the emergency kit contains

    When automatic encrypted backups are configured, Home Assistant generates an encryption key and offers an emergency kit for download. Home Assistant’s official backup guidance says encrypted backups require this key for restoration. The kit records the recovery information and identifies the backup configuration it belongs to.

    The emergency kit should be stored separately from the Home Assistant machine. If the only copy is on the same disk that fails, the backup may become unusable precisely when it is needed.

    Before attempting another restore

    1. Preserve the original backup file without renaming or modifying its contents.
    2. Make a second copy on another storage device.
    3. Record the backup filename, creation date, size, and storage location.
    4. Do not wipe the old Home Assistant installation if it may still contain the working backup configuration.
    5. Do not post the encryption key, backup file, or emergency kit publicly.
    6. Keep power stable during any restore, especially on Raspberry Pi or removable storage.

    A backup can contain credentials, tokens, Wi-Fi details, device keys, location history, and personal automation data. Treat both the archive and emergency kit as sensitive secrets.

    Step 1: Confirm that the prompt is for backup encryption

    Read the restore screen carefully. An encryption-key prompt is different from the Home Assistant owner login, onboarding account creation, full-disk encryption, a network-storage password, or a cloud-provider sign-in.

    The emergency-kit key is associated with Home Assistant backups. Trying account passwords will not decrypt the archive and can waste time or trigger unrelated account protections.

    Step 2: Re-download the emergency kit from the working system

    If the original Home Assistant installation is accessible:

    1. Open Settings → System → Backups.
    2. Open the automatic-backup configuration.
    3. Locate the emergency-kit or encryption-key option.
    4. Download a fresh copy.
    5. Save it to two separate secure locations.
    6. Label it with the Home Assistant instance and date.

    Home Assistant’s 2025 backup announcement states that the emergency kit is available to download again from backup settings. Do this before migrating storage, replacing hardware, reinstalling Home Assistant OS, or experimenting with the old disk.

    Step 3: Search likely safe locations methodically

    If the old instance is unavailable, search without changing the backup:

    • Your computer’s Downloads and Documents folders.
    • An encrypted password-manager attachment or secure note.
    • An encrypted USB drive or external backup disk.
    • A private cloud-storage folder you intentionally chose.
    • A printed recovery folder or sealed offline record.
    • Another administrator’s approved secure storage.

    Search by the Home Assistant instance name, “emergency kit,” “backup,” the approximate setup date, and likely file extensions. Verify the contents locally without sharing them.

    Do not use random online “decrypt backup” services. Uploading a Home Assistant backup to an unknown site can expose every secret stored in the installation.

    Step 4: Check the configured backup destination

    Home Assistant can store automatic backups in enabled locations. The official documentation lists local storage, Home Assistant Cloud for subscribers, network storage, and locations supplied by backup-capable integrations. Determine which destination was enabled when the backup was created.

    If Home Assistant Cloud was used, the latest stored backup may be accessible through the authorized cloud account even when the Home Assistant hardware has failed. Cloud-stored backups are encrypted, so the emergency key is still required. Sign in only through the official service.

    Step 5: Match the kit to the backup

    Do not assume the newest key unlocks every old archive. A backup may belong to an earlier installation or backup configuration. Keep multiple kits clearly labeled rather than replacing older copies automatically.

    1. Start with the kit whose date and instance name best match the backup.
    2. Enter the key exactly, avoiding added spaces or line breaks.
    3. If it fails, stop and verify the backup and kit identity.
    4. Try another legitimate kit only when you have evidence it may match.
    5. Never edit the archive to remove encryption markers.

    Step 6: Verify backup integrity before blaming the key

    A damaged or incomplete archive may produce a restore failure that looks like a key problem. Compare the file size with the source storage and copy it again if the transfer was interrupted. Avoid restoring directly from an unstable browser upload, failing SD card, or unreliable network share.

    If the source system still works, create a new manual backup, download its emergency kit, and test with that known pair. Home Assistant’s general backup guidance recommends excluding large media and share folders when appropriate because oversized backups take longer to create and restore. Do not exclude essential configuration merely to make the file smaller.

    Step 7: Prepare the destination correctly

    Use the restore path supported by your Home Assistant installation type. A complete Home Assistant OS migration differs from moving a Container installation or restoring selected folders manually. Confirm the destination has enough free storage—ideally comfortably more than the archive size because extraction requires working space.

    Connect the destination to stable power and a reliable network. On small single-board computers, avoid suspect SD cards or underpowered adapters. A restore interrupted by power loss can leave the destination inconsistent even though the original backup remains safe.

    Step 8: Restore with the correct key

    1. Upload or select the preserved backup through the supported restore interface.
    2. Enter the matching encryption key from the emergency kit.
    3. Select a full or partial restore intentionally.
    4. Start the restore and allow it to finish without refreshing repeatedly.
    5. Expect the interface to become temporarily unavailable during restart.
    6. Reconnect using the appropriate local address after sufficient time.

    A large backup can take a long time. Repeatedly restarting the host because the page is temporarily unavailable can convert a slow restore into a failed one. Check host activity and network reachability before intervening.

    How to verify the restored system

    1. Confirm the expected Home Assistant version and installation type.
    2. Check integrations for reauthentication or missing hardware.
    3. Verify Zigbee, Z-Wave, Matter, Thread, Bluetooth, and USB adapter mappings.
    4. Test several non-critical automations.
    5. Check dashboards, users, areas, scripts, and helpers.
    6. Review logs for repeated database, storage, or integration errors.
    7. Create a new backup only after the restored instance is stable.

    Some integrations intentionally require reauthentication after migration. USB device paths, IP addresses, multicast routing, and radio assignments can also change. These are post-restore environment issues, not proof that the backup was bad.

    If you cannot recover the key

    There is no responsible shortcut around correctly implemented encryption. If the original instance is still accessible, recover or re-download the emergency kit from it. If a trusted cloud service holds the backup, check its official recovery path. If neither the matching key nor a functioning original system exists, you may have to build a new Home Assistant installation and reconnect devices.

    Before rebuilding, preserve the old storage and all backup copies. A later discovery of the correct emergency kit may make restoration possible. Rebuilding immediately on the same disk can destroy that option.

    Rollback and recovery

    If a restore fails, do not modify the original archive. Save logs and error text, shut down the destination cleanly if possible, and return to the previous known-good boot disk or instance. When migrating hardware, keep the old system powered off but intact until the new one has operated successfully for several days.

    When to escalate

    Contact official Home Assistant support channels or the relevant installation project with the Home Assistant version, installation type, destination hardware, backup creation date and size, exact error text, and restore stage. Remove secrets from screenshots and logs. Never provide the emergency key or backup archive to strangers offering to fix it.

    Prevention: a practical 3-2-1 plan

    • Keep at least three copies of important data.
    • Use at least two different storage types or locations.
    • Keep at least one copy off the Home Assistant host.
    • Store the emergency kit separately in two secure places.
    • Label kits with the instance and date.
    • Test that a backup and its key are available before major updates.
    • Review retention rules so a bad new backup does not replace the only good copy.
    • Create a fresh manual backup before hardware, radio, database, or network migrations.

    Plan for the case where no matching emergency kit can be found

    If every legitimate storage location has been checked and no matching encryption key exists, pause before reinstalling or overwriting anything. Encryption is intended to prevent recovery without the key. A normal account password, recovery-mode login, cloud subscription, or new emergency kit cannot substitute for the key that protected an older backup.

    Preserve every remaining source: the original Home Assistant disk, downloaded backup archives, network-storage snapshots, cloud copies, and older emergency kits. Label copies with dates and do not run repair utilities directly against the only surviving disk. If the original system can still boot intermittently, prioritize downloading a fresh backup and its matching emergency kit. If storage hardware is failing, make a sector-level image with appropriate recovery expertise before repeated boots cause further damage.

    A partial manual rebuild may be the only safe path when the key is unavailable. Recreate the new Home Assistant owner account, reinstall integrations from official sources, reauthenticate cloud services, and add radios or devices carefully. Do not copy unknown database fragments or secret files into a clean installation without understanding their compatibility and security impact.

    Build a backup recovery drill instead of trusting an untested archive

    A backup is useful only when its archive, key, storage location, and restore procedure remain available together. Schedule a periodic recovery review. Confirm that automatic backups are completing, verify their sizes are plausible, download the current emergency kit, and store it separately in at least two protected locations. Keep one offline copy when practical and document which Home Assistant instance it belongs to.

    Do not expose a backup or emergency kit merely to test it. Use an isolated, supported environment and prevent the restored instance from taking control of production radios, locks, alarms, thermostats, or automations. A test restore should confirm that the key unlocks the archive and that essential configuration is present without allowing two controllers to operate the same home simultaneously.

    Information to record before requesting help

    Record the Home Assistant version that created the backup, installation type, archive filename and size, destination type, restore environment, exact stage of failure, and the complete redacted error. Say whether the key prompt rejects the key immediately or whether failure occurs later during extraction. This distinction helps separate a mismatched key from damaged storage, insufficient space, or a restore-process problem. Never upload the archive, emergency kit, secrets file, tokens, or unredacted diagnostics to a public forum.

    Sources

    Last reviewed: September 8, 2026.

    Related Troubliq guides: Use the safe diagnostic method and browse all troubleshooting guides.

    Decision guide: which recovery path should you choose?

    If the original Home Assistant system still starts, the safest path is to re-download the emergency kit there, create a fresh backup, copy both items off the host, and then retry the migration. If the original system does not start but its disk is intact, preserve that disk before attempting repair. Work from a clone or separate destination whenever possible.

    If the backup is stored in Home Assistant Cloud or another supported destination, retrieve it only through that provider’s official authenticated interface. A cloud copy does not eliminate the encryption requirement; it protects availability, while the emergency kit protects confidentiality. You need both the archive and its matching key.

    If you have the correct key but restoration still fails, investigate file integrity, free disk space, installation type, and transfer errors before concluding the encryption is wrong. If you have no key but retain access to the old instance, recover the kit there. If neither the matching key nor the original instance exists, preserve all media and prepare for a clean rebuild rather than repeatedly modifying the only backup.

    Find your next troubleshooting path

    Use the related guide that matches the next confirmed layer of the failure. Avoid changing unrelated systems at the same time.

  • HomeKit device says already paired in Home Assistant: safe recovery without losing setup

    HomeKit device says already paired in Home Assistant: safe recovery without losing setup

    Direct answer: A HomeKit device usually reports “already paired” because it still belongs to Apple Home, another HomeKit controller, or a previous Home Assistant pairing record. HomeKit accessories generally accept only one controller pairing at a time. First identify the current owner, remove the accessory from that controller, wait for it to become discoverable, and pair it with Home Assistant’s HomeKit Device integration. Factory reset is a last resort because it can erase Wi-Fi or Thread credentials, scenes, vendor settings, and automations.

    Symptoms and scope

    • Home Assistant discovers the accessory but pairing fails with an already-paired or unavailable message.
    • The HomeKit code is accepted, then setup stops.
    • The device still appears in Apple Home or another Home Assistant installation.
    • A restored Home Assistant instance sees the accessory but cannot control it.
    • The accessory was removed from Apple Home but does not appear in Home Assistant.
    • A Thread accessory keeps returning to an old Thread network.

    This guide concerns importing a physical HomeKit accessory into Home Assistant with the HomeKit Device integration, formerly called HomeKit Controller. It is different from HomeKit Bridge, which exports Home Assistant entities to Apple Home. Confusing the two integrations can send troubleshooting in the wrong direction.

    How HomeKit ownership works

    A HomeKit accessory establishes an encrypted pairing relationship with one controller. The controller might be an Apple Home, Home Assistant, or another compatible ecosystem. Adding a device to Apple Home and then trying to import it directly into Home Assistant without removing it from Apple Home normally fails because the accessory is still owned.

    The official Home Assistant documentation describes a useful Wi-Fi workflow: use Apple Home or the manufacturer’s app to place the device on the local network, then remove it from Apple Home. Removing it opens the HomeKit pairing again while the accessory may remain connected to Wi-Fi. Home Assistant can then discover and pair it locally.

    Thread devices require extra care. Removing a device from Apple Home without resetting it can leave its Thread credentials intact, allowing Home Assistant to discover it over the existing Apple Thread network. Resetting it may erase those credentials and require Bluetooth commissioning or provisioning onto Home Assistant’s preferred Thread network.

    Before you begin

    1. Find the eight-digit HomeKit pairing code on the device, packaging, manual, or display.
    2. Record the device’s current name, room, vendor app account, and automations.
    3. Confirm whether it connects through Wi-Fi, Ethernet, Bluetooth, or Thread.
    4. Back up Home Assistant before removing an existing integration or changing Thread networks.
    5. If it controls a lock, garage door, alarm, valve, heater, or other safety-sensitive equipment, keep the manufacturer’s supported control method available throughout the change.

    Home Assistant’s documentation states that a lost HomeKit pairing code cannot be recovered by Home Assistant. Contact the manufacturer if the code is missing. Do not repeatedly guess codes; some accessories impose timeouts.

    Step 1: Make sure you are using the right integration

    Open Settings → Devices & services. A discovered accessory intended for import should appear under HomeKit Device. HomeKit Bridge is not the pairing destination for a physical accessory; it exposes existing Home Assistant entities to Apple Home.

    If the accessory already exists as a vendor integration—such as a local manufacturer integration—decide which method you actually want. Do not pair through multiple paths merely to fix discovery. Duplicate integrations can create duplicate entities and conflicting automations.

    Step 2: Identify the controller that currently owns the accessory

    Check Apple Home, any previous Home Assistant server, family members’ homes, and vendor gateways. A device visible in Apple Home is paired even if it is offline. If you migrated Home Assistant, the old instance or an incomplete restore may still hold the pairing relationship.

    Do not delete the Home Assistant device entry first unless you are certain the accessory can be unpaired or reset. Deleting the controller record while the accessory retains its pairing can leave the two sides out of sync.

    Step 3: Remove it cleanly from Apple Home

    For a Wi-Fi or Ethernet accessory currently in Apple Home:

    1. Confirm it is online in Apple Home.
    2. Record any Apple Home scenes or automations using it.
    3. Use Apple Home’s remove-accessory action.
    4. Keep the accessory powered and connected to the same LAN as Home Assistant.
    5. Wait several minutes for HomeKit discovery to update.
    6. Check Home Assistant’s discovered integrations again.

    The important distinction is remove versus factory reset. Removal ends Apple Home’s controller pairing. A reset also clears the accessory’s local configuration and may be unnecessary for an IP device.

    Step 4: Check local discovery

    HomeKit IP accessories are normally discovered through local multicast DNS. Being able to ping the device does not prove mDNS can cross a VLAN, guest network, wireless isolation boundary, VPN, or container network. Place Home Assistant and the accessory on the same local network temporarily if possible.

    Check these conditions:

    • Client isolation or guest-network isolation is disabled for the test.
    • UDP multicast traffic is not blocked between the relevant interfaces.
    • The Home Assistant host has normal local-network access.
    • A container or VM network exposes multicast correctly.
    • No stale DNS override sends the accessory or Home Assistant through a public route.

    Change one network condition at a time. Avoid permanently opening broad inter-VLAN access just to make discovery work; a properly scoped mDNS reflector and the required device traffic are safer.

    Step 5: Pair an IP accessory

    1. Open the discovered HomeKit Device card in Settings → Devices & services.
    2. Select Configure.
    3. Enter the HomeKit code exactly as printed.
    4. Wait for the accessory to exchange keys and create entities.
    5. Assign it to an area and finish setup.

    If the code fails immediately, confirm you are using the HomeKit code rather than a Matter code, serial number, Wi-Fi password, or vendor setup PIN. Preserve the dashes or remove them only as the interface requests.

    Step 6: Handle Bluetooth accessories

    A Bluetooth HomeKit accessory must be within reliable radio range of Home Assistant or a supported ESPHome Bluetooth proxy. Battery devices may need to be awakened during pairing. Bluetooth pairing can take longer than IP pairing, so do not restart the accessory repeatedly while the exchange is active.

    Verify the Bluetooth adapter or proxy works with another known device. If the accessory was previously paired or joined to Thread, the official documentation advises resetting it before Bluetooth-based setup so old controller or Thread information does not interfere. Follow the manufacturer’s exact reset sequence and confirm the device re-enters pairing mode.

    Step 7: Handle Thread accessories without destroying the working mesh

    If a HomeKit-over-Thread accessory currently works in Apple Home and you want it to stay on Apple’s Thread network, remove it from Apple Home but do not reset it. The device can retain its Thread details and may then be discovered by Home Assistant over Thread. Pair it using the printed HomeKit code.

    If instead you want to move it onto Home Assistant’s preferred Thread network, first verify a working border router and known credentials. Pair through Bluetooth if required, then use the device configuration to provision the preferred Thread credentials. Do not delete Thread datasets or reset border routers to solve a single accessory problem.

    Step 8: Recover after a Home Assistant migration or partial restore

    A complete Home Assistant backup normally carries integration configuration, but a partial restore or manually rebuilt instance may not contain the old HomeKit pairing keys. The accessory can remain paired to keys the new instance does not have.

    1. Confirm whether a complete backup from the working instance exists.
    2. Prefer restoring the relevant known-good backup over resetting every accessory.
    3. If restoration is not possible, remove the accessory from its current controller through the supported UI.
    4. Reset only the individual accessory that cannot be cleanly unpaired.
    5. Pair one device and verify stability before repeating the process.

    If pairing succeeds but no entities appear

    Home Assistant supports many common HomeKit domains, including lights, switches, locks, climate devices, covers, fans, sensors, and alarms. The official documentation notes that an unsupported device type may appear in the Device Registry without creating usable entities. That is different from a pairing failure.

    Check the device page, disabled entities, diagnostic entities, and integration documentation. Do not repeatedly remove and re-pair a successfully paired accessory because its service type is unsupported.

    How to verify the fix

    1. Confirm the accessory is listed under HomeKit Device.
    2. Operate one non-destructive control in Home Assistant.
    3. Physically verify the device responds.
    4. Change the device state outside Home Assistant and confirm a push update returns.
    5. Restart Home Assistant once and confirm the device reconnects.
    6. For Thread, verify the reported Thread status after the mesh settles.

    Rollback and recovery

    If Home Assistant pairing fails after clean removal, you may re-add the accessory to Apple Home using its original pairing code, provided it remains in pairing mode. If the accessory was factory-reset, restore vendor settings and automations deliberately. For a security device, follow the manufacturer’s recovery process and test all physical safety functions.

    When to escalate

    Collect the Home Assistant version, device manufacturer and model, firmware, connection type, integration diagnostics, and relevant logs with secrets removed. Contact the manufacturer if the pairing code is missing or the reset process does not reopen pairing. Report reproducible integration failures to Home Assistant only after confirming the device is unpaired and discoverable.

    Prevention

    • Store HomeKit codes securely before installation.
    • Document which controller owns each accessory.
    • Back up Home Assistant before migrations.
    • Choose a Thread network intentionally and keep its credentials recoverable.
    • Avoid unnecessary factory resets.
    • Do not confuse HomeKit Device with HomeKit Bridge.

    Source

    Last reviewed: September 8, 2026.

    Related Troubliq guides: Thread credentials are synced but commissioning fails, Matter device pairs but shows unavailable, and the safe diagnostic method.

    Decision guide: remove, reset, or restore?

    Choose the least disruptive path that matches the evidence. If the accessory is visible and controllable in Apple Home, remove it from Apple Home first; do not reset it. If it is an IP accessory that was added to Wi-Fi through Apple Home, keep it powered after removal so it can remain on the network and advertise for a new controller. If it is a Thread accessory that should remain on an Apple Thread network, removal without reset preserves the best chance of retaining those network credentials.

    Use a factory reset only when the accessory cannot be removed from the controller that owns it, its previous controller no longer exists and no usable backup remains, or the manufacturer explicitly requires a reset to reopen pairing. Use restoration instead when the problem began after migrating Home Assistant and a complete backup from the working controller is available. Restoration can recover the pairing keys and prevent a house-wide reset campaign.

    After each action, wait for discovery to settle and test before escalating. Removing, resetting, restoring, and changing VLAN rules at the same time destroys the evidence needed to identify the real cause.

    How to preserve the original controller relationship before a reset

    Before resetting an accessory, identify every place where it may already be paired. Check Apple Home on each household member’s device, any older Home Assistant installation, vendor apps, and previous hubs that may still be powered. A HomeKit pairing record belongs to the controller’s Home data, not merely to the phone used during setup. Removing an app, changing phones, or deleting an integration card does not necessarily release the accessory.

    If the accessory still responds through Apple Home, record its room, name, scenes, automations, and any bridge or Thread border router involved. Remove it from the owning controller while it is powered and reachable, then wait for that removal to complete before attempting another pairing. This clean removal is preferable to a factory reset because it gives the controller an opportunity to discard its relationship and can preserve network settings that the accessory is designed to retain.

    For a bridged accessory, determine whether the HomeKit code belongs to the bridge rather than the individual endpoint. Resetting a child bulb, sensor, or switch may not clear the bridge-level pairing and can create extra recovery work. Consult the manufacturer’s instructions for the exact model because button sequences, LED meanings, and reset depths differ.

    Network checks when the pairing code is accepted but setup still fails

    An “already paired” message can be followed by a second problem: the old pairing is cleared, but discovery or communication fails. Confirm that the Home Assistant host and accessory can exchange local traffic. Multicast DNS must cross the relevant Wi-Fi or VLAN boundary, client isolation must not block peers, and firewall rules must permit the local path. For Thread accessories, confirm that a compatible border router is operational and that the phone used for commissioning has Bluetooth and local-network permissions.

    Do not merge these stages into one diagnosis. First prove that ownership was released; then investigate discovery, networking, or Thread credentials. This separation prevents repeated resets from hiding the actual fault.

    Evidence to collect for a useful support request

    If the accessory remains unavailable, record the exact model, firmware, connection type, Home Assistant version, installation type, integration name, and the complete redacted error. State whether the device is visible in Apple Home, the vendor app, Home Assistant discovery, or a network scan. Include the order of removal and pairing attempts, but never share HomeKit setup codes, QR codes, Wi-Fi credentials, diagnostic archives containing secrets, or account tokens.

    Find your next troubleshooting path

    Use the related guide that matches the next confirmed layer of the failure. Avoid changing unrelated systems at the same time.

  • MQTT entities unavailable after Home Assistant restart

    MQTT entities unavailable after Home Assistant restart

    Direct answer: When MQTT entities become unavailable after Home Assistant restarts, the most common problem is not the entity itself. Home Assistant has reconnected to the broker, but it has not yet received the discovery or availability messages required to rebuild the entity and mark the device online. The safest fix is to verify the broker connection, confirm the device republishes discovery after Home Assistant’s birth message, and check whether the availability message is retained. Do not delete the MQTT integration or recreate every entity until you know which message is missing.

    What this problem looks like

    • MQTT entities worked normally before a Home Assistant restart but return as unavailable.
    • The device is powered and still publishes data, yet its entities do not recover.
    • Reloading MQTT temporarily restores some or all entities.
    • Entities appear only after the physical device restarts.
    • Manually republishing a discovery payload makes the entity return.
    • The broker log shows Home Assistant reconnecting, but the expected discovery or online message is absent.

    This guide applies to MQTT discovery and manually configured MQTT entities. It is especially relevant to devices or bridges that generate Home Assistant discovery payloads, including custom firmware, gateways, scripts, and home-built sensors.

    Why MQTT entities can stay unavailable

    MQTT is message based. Home Assistant cannot infer a device’s current state merely because the broker is reachable. Depending on the entity configuration, it may need several different messages:

    • A discovery configuration message describing the entity.
    • A state message containing the current value.
    • An availability message such as online.
    • A new message before an expire_after timer runs out.

    Home Assistant’s MQTT documentation explains that, during startup, existing discovered devices and entities can remain unavailable until their discovery messages are received and processed. It recommends that devices subscribe to Home Assistant’s birth message and use it as a trigger to resend discovery. This matters when the original discovery configuration was not retained or when the publishing device started before Home Assistant.

    Availability is separate from state. A sensor may continue publishing a number while its availability topic still says offline. Conversely, an entity can be marked online but have an old or unknown state. Diagnose these message paths separately.

    Before changing anything

    1. Record one affected entity ID and its device name.
    2. Open the MQTT integration and download diagnostics if available.
    3. Copy the entity’s discovery topic, state topic, and availability topic.
    4. Note whether the failure happens after every restart or only intermittently.
    5. Back up configuration files before editing YAML, templates, automations, or broker settings.

    Avoid clearing retained topics broadly. Retained MQTT messages may be controlling discovery and availability for many devices. Deleting them without an exact topic list can remove working entities or revive stale configurations in confusing ways.

    Step 1: Confirm Home Assistant is connected to the correct broker

    Open Settings → Devices & services → MQTT. Confirm the integration is loaded and does not show an authentication or connection error. If you recently moved the broker, changed credentials, or restored a backup, verify the host, port, TLS setting, username, and broker instance.

    Use the MQTT listening tool in Home Assistant to subscribe temporarily to the affected device’s topic tree, such as device-name/#. Use the narrowest safe filter you know; avoid subscribing to # on a busy system for long periods. Restart or wake the affected device and observe whether messages arrive.

    If no messages arrive, the problem is upstream of the entity: device connectivity, broker permissions, an incorrect topic, or the publisher itself. If messages do arrive, continue and distinguish discovery, state, and availability.

    Step 2: Verify the discovery configuration is replayed

    MQTT discovery topics normally begin with the configured discovery prefix, commonly homeassistant/. Listen for the exact configuration topic used by the affected entity. A valid discovery message should contain the entity configuration and should be published again when needed.

    If the configuration is retained, a newly connected Home Assistant client should receive it from the broker. If it is not retained, the device or bridge must republish it after Home Assistant comes online. Many reliable publishers do both: retain the discovery configuration and also respond to the Home Assistant birth message.

    Check the publisher documentation before changing retain behavior. Retaining a discovery configuration is normal; retaining every kind of state or command message is not automatically correct.

    Step 3: Test the Home Assistant birth-message path

    Home Assistant publishes a birth message when MQTT becomes available. A discovery publisher can subscribe to that status topic and resend its configurations when it sees the online payload. If entities appear only after restarting the device, this replay path is probably missing or broken.

    1. Identify the birth topic and payload configured for Home Assistant.
    2. Confirm the publishing device or bridge subscribes to that exact topic.
    3. Check capitalization and spacing in the expected payload.
    4. Restart only the MQTT integration or Home Assistant once while listening.
    5. Verify that the publisher responds by sending its discovery configurations again.

    Do not create an automation that repeatedly floods discovery messages. One response to the relevant birth event is enough.

    Step 4: Inspect the availability topic and retained flag

    For an entity with an availability topic, Home Assistant uses the configured available and unavailable payloads. The defaults are often online and offline, but publishers can use other values. The payload must match exactly.

    The official MQTT binary-sensor documentation notes that when the availability message is not retained, a sensor may display unavailable after Home Assistant starts because no current availability message has arrived. Retaining the latest availability status allows a subscriber to receive it immediately. A device should normally publish a retained offline message through its Last Will and Testament and replace it with a retained online message after a successful connection.

    Check for these failure patterns:

    • The online message uses a different topic than the entity configuration.
    • The device publishes Online while Home Assistant expects online.
    • A retained offline message remains after the device reconnects.
    • Multiple availability topics require all topics to be online when any was intended.
    • The publisher reconnects without sending its current online state.

    Step 5: Separate state retention from availability retention

    Do not assume the state message should be retained because availability should be retained. The correct choice depends on the entity. A retained temperature reading can provide an immediate value after restart, but it may also present a stale reading as current. Home Assistant’s MQTT sensor documentation cautions against retaining state when expire_after is used because replaying an old retained value can make an expired sensor appear available again.

    For event-like data—button presses, motion events, one-shot commands—retaining the state is usually wrong. For a slowly changing measurement, retaining may be useful if the age and availability logic are handled correctly. Follow the device integration’s documentation.

    Step 6: Check expire_after and message frequency

    If the entity works briefly and then becomes unavailable, inspect expire_after. The publisher must send a valid update before the timer expires. A sensor configured to expire after 60 seconds cannot remain available if it reports every five minutes.

    Compare the configured expiry with the real publish interval, including battery-saving sleep. Allow enough margin for Wi-Fi reconnection, broker delays, and normal jitter. Do not reduce battery life by forcing excessive updates merely to satisfy an unnecessarily short expiry.

    Step 7: Look for stale or duplicate discovery configurations

    If the same physical device has multiple entities or old names, search the broker’s retained discovery topics for obsolete configurations. A changed unique_id, discovery topic, or device identifier can create a second entity instead of updating the first.

    Remove only a configuration you have positively identified. The standard discovery removal method is to publish an empty retained payload to the exact obsolete configuration topic. Before doing so, save the topic and payload so you can restore it. Never bulk-delete retained messages as a first troubleshooting step.

    How to verify the fix

    1. Restart Home Assistant once; do not restart the MQTT device at the same time.
    2. Confirm the broker connection returns normally.
    3. Watch for the Home Assistant birth message.
    4. Confirm discovery is replayed or delivered from retained storage.
    5. Confirm the current availability message is received.
    6. Confirm a fresh state arrives and the entity becomes available.
    7. Wait longer than the previous failure interval to ensure it stays available.

    Rollback and recovery

    If a configuration change makes the problem worse, restore the saved discovery payload, return the previous retain settings, and restart only the affected publisher. If you edited YAML, restore the backup and validate configuration before restarting Home Assistant. If many devices fail simultaneously, investigate the broker, credentials, DNS, firewall, storage, or MQTT integration rather than resetting every endpoint.

    When to escalate

    Collect the Home Assistant version, installation type, MQTT integration diagnostics, broker version, exact affected topics with secrets removed, timestamps, and a short sequence that reproduces the failure. Report firmware-specific behavior to the device or bridge project. Never post broker passwords, access tokens, private certificates, or complete diagnostics without reviewing them for sensitive information.

    Prevention

    • Make discovery publishers respond to the Home Assistant birth message.
    • Retain discovery configurations and availability status where the publisher supports it correctly.
    • Use stable unique IDs and topic names.
    • Document state, availability, and expiry behavior separately.
    • Back up broker configuration and custom publisher code.
    • Test one controlled Home Assistant restart after firmware or broker changes.

    Use a controlled message trace to prove which stage fails

    When several MQTT entities behave differently, capture a short, time-bounded trace for one affected device. Begin listening before restarting Home Assistant, note the timestamp of the birth message, and then record the order in which discovery, availability, and state messages arrive. Remove credentials and sensitive payload fields before saving or sharing the trace.

    The sequence matters. If discovery arrives but availability never follows, investigate the publisher’s connection and Last Will configuration. If availability arrives but state does not, examine the device’s publish interval, sleeping behavior, and state topic. If no discovery arrives until the device restarts, the birth-message subscription or retained discovery configuration is the likely gap. A trace converts a vague “unavailable” symptom into a specific missing message.

    Special considerations for sleeping and battery-powered devices

    A sleeping sensor may not respond immediately to a Home Assistant restart. Its state and availability design should reflect the expected wake interval. Do not force a battery device to remain awake or publish excessively simply to make the interface update sooner. Compare the configured expiration period with the longest normal sleep interval, including weak-signal retries and seasonal reporting behavior.

    Some publishers intentionally omit an availability topic and rely on the age of the last state. Others use a bridge-level availability topic shared by many child devices. Identify the model actually implemented before changing retain flags. Applying a generic online/offline pattern to a sleeping product can mark a healthy device unavailable between reports.

    Broker-session and permission checks

    After credentials, TLS settings, or access-control lists change, a publisher may connect but lose permission to publish discovery or availability topics. Review broker logs for denied subscriptions or publishes, using the exact client ID and topic. Also check for duplicate client IDs: MQTT brokers normally disconnect the earlier session when another client connects with the same identifier, which can create a repeating online/offline pattern.

    Make one reversible change at a time. Correct the topic permission or client ID, reconnect the publisher, and repeat the controlled trace. Avoid broad wildcard permissions as a shortcut; grant only the topic access the device or bridge requires.

    What to include when escalating

    Provide the broker version, Home Assistant version and installation type, publisher firmware, discovery prefix, redacted topic names, QoS and retain settings, availability mode, expiry configuration, and a timestamped message sequence. State whether reloading MQTT, restarting Home Assistant, or restarting the publisher changes the outcome. Keep broker passwords, certificates, access tokens, unique device identifiers, and complete unredacted payloads private.

    Evidence and testing disclosure

    Applies to: current Home Assistant MQTT discovery and manually configured MQTT entities, including publishers that use birth messages, availability topics, retained configuration, or expire_after. Expected result: after Home Assistant restarts, the broker reconnects, discovery is replayed or retained, the current availability arrives, and a fresh state restores the entity without restarting the physical device. Verification: capture one time-bounded trace in the order birth → discovery → availability → state. Rollback: restore saved topic payloads and previous retain or expiry settings if a change fails. Testing status: this guide follows official Home Assistant MQTT behavior; Troubliq did not test every third-party publisher. Last reviewed September 30, 2026.

    Sources

    Last reviewed: September 8, 2026.

    Related Troubliq guides: Start with the safe diagnostic method and browse all troubleshooting guides.

    Decision guide: what should be retained?

    Retain the discovery configuration when the device should be reconstructed automatically after Home Assistant reconnects. Retain the latest availability status when subscribers need to know immediately whether the device is online, and configure Last Will and Testament so an unexpected disconnect leaves an accurate offline status. Treat state retention as a separate design choice.

    For a temperature, energy total, or other slowly changing measurement, a retained state can be reasonable when users understand its timestamp and no conflicting expiry logic exists. For motion, button presses, doorbell events, and commands, a retained state can replay an old event as though it just happened and is usually unsafe. For sensors using expire_after, follow the official warning about retained state and test restart behavior carefully.

    If you do not control the publisher, do not compensate with broad broker cleanup. Document the exact topics, capture a short message trace, and report the missing discovery replay or availability behavior to the device project. A precise report is more useful than repeatedly reloading the integration.

    Find your next troubleshooting path

    Use the related guide that matches the next confirmed layer of the failure. Avoid changing unrelated systems at the same time.

  • Zigbee2MQTT interview state failed: safe fixes

    Zigbee2MQTT interview state failed: safe fixes

    Direct answer: A Zigbee2MQTT “interview failed” message means the device joined the Zigbee network but Zigbee2MQTT could not finish reading the descriptors, endpoints, clusters, or attributes needed to identify and control it. Keep battery devices awake, retry near a known-good coordinator or router, confirm the exact model is supported, and read the first failed interview step before changing firmware or rebuilding the network.

    What “interview state failed” actually means

    Joining and interviewing are separate. Joining establishes the device’s network relationship and security material. The interview then asks the device what it is: its node descriptor, active endpoints, supported clusters, manufacturer identifiers, and capabilities. A device can therefore appear in Zigbee2MQTT and still have no useful controls because the second stage did not complete.

    Do not confuse this with a coordinator startup failure. If Zigbee2MQTT cannot open the adapter, the interview never begins. Likewise, an MQTT connection problem can prevent Home Assistant from seeing results even when the Zigbee interview succeeded. Use the first error in the log to identify the layer.

    Symptoms and scope

    • The log reports a successful join followed by interview failed or interview state failed.
    • The device appears with an incomplete name, unsupported label, or no exposes.
    • Pairing repeatedly stops at the same descriptor, endpoint, cluster, or attribute request.
    • A battery device joins only while a button is pressed and then becomes silent.
    • One model fails while other devices interview normally.
    • Several models fail after a coordinator, firmware, channel, or network change.

    Preserve evidence before retrying

    Open the Zigbee2MQTT log and save the sequence from the first join message through the failure. Record the Zigbee2MQTT version, coordinator model and firmware, adapter type, Zigbee channel, installation method, device brand, printed model number, and any manufacturer/model identifiers shown in the log. Note whether permit-join targeted the coordinator or a router.

    Back up the coordinator and Zigbee2MQTT data directory before updating firmware, changing channels, or modifying network keys. Redact network keys, MQTT credentials, IEEE addresses when unnecessary, public addresses, tokens, and other identifiers before sharing logs.

    Ranked causes

    Likely causeEvidenceFirst safe test
    Battery device fell asleepInterview begins, then times out at varying stepsUse the manufacturer’s wake sequence throughout one retry
    Weak or unstable parent linkRetries, timeouts, or success only very close to the coordinatorInterview near a known-good parent without moving the whole network
    Unsupported fingerprint/converterOne exact model fails consistently while others workCheck the exact identifiers in the supported-device database
    Low battery or unstable powerDevice resets or leaves during interviewInstall a fresh recommended battery or verify the power supply
    Coordinator/firmware problemSeveral unrelated devices fail after the same changeCheck coordinator health and compatibility before updating again
    2.4 GHz interferencePacket loss affects multiple devices or one locationCompare one controlled retry in a cleaner location
    Stale partial entryRepeated retries reuse an incomplete recordRemove only the failed device entry, reset that device, and retry

    Step 1: confirm the exact model is supported

    Search the official Zigbee2MQTT supported-devices database using the exact model identifier, not only the retail name. Manufacturers may reuse product names while changing internal hardware or fingerprints. A visually identical device can require a newer converter or expose different clusters.

    If the device is listed, compare any pairing notes, required button sequence, and minimum Zigbee2MQTT version. If it is not listed, do not assume it is safe to substitute a similar converter. Preserve the interview log and identifiers for a device-support request. An open support issue is a report, not proof that all units are affected.

    Step 2: keep sleepy devices awake

    Battery devices often return to sleep before the interview completes. Follow the manufacturer or Zigbee2MQTT pairing instructions exactly. Some devices require repeated short presses, periodic presses, or holding a button until a light changes. Random rapid pressing can reset the device again or trigger a different mode.

    Start permit-join first, reset the device, and maintain the documented wake action until the log reports a successful interview. If the failure advances farther each time, sleep or link reliability is more likely than an unsupported device. If it fails at the identical unsupported descriptor or converter step, investigate model support.

    Step 3: choose the pairing parent deliberately

    Interview once near the coordinator or a proven compatible mains-powered router. Zigbee2MQTT can permit joining through a selected device, which is useful when the final location depends on a router. Keep USB coordinators away from USB 3 equipment and other radio-noise sources using a quality extension cable where recommended.

    Do not pair every device beside the coordinator and then move it across the building. Some end devices choose a parent during joining and may not immediately find a better route after relocation. A controlled close-range test is diagnostic; if it succeeds, remove the temporary entry, reset the device, and pair it in the intended location through an appropriate router.

    Step 4: check power before software

    Use a fresh battery of the correct chemistry and size when the existing battery is uncertain. A device may have enough voltage to blink or begin joining but still reset during sustained radio activity. For mains-powered products, stop if wiring, heat, swelling, odor, sparks, or moisture are involved; use a qualified electrician or the manufacturer rather than continuing software tests.

    For USB-powered routers or coordinators, verify the cable and supply. Intermittent USB power can resemble a device interview problem when the coordinator silently reconnects. Check the host log for USB disconnects at the same timestamp.

    Step 5: read which interview request failed

    A node-descriptor timeout points toward the device not answering early in the process. Failure while discovering active endpoints may indicate sleep, link loss, or unusual firmware behavior. A consistent cluster or attribute-read failure can expose a converter expectation or nonstandard implementation. A manufacturer/model fingerprint mismatch points toward device support rather than radio range.

    Use debug logging only long enough to reproduce one clean attempt, then return to the normal level. More logs are not automatically better; repeated attempts can bury the first meaningful exchange. Keep timestamps synchronized so coordinator, Zigbee2MQTT, and host messages can be compared.

    Step 6: distinguish one-device failures from system failures

    If one model fails while several known-good devices interview successfully in the same location, focus on its wake sequence, power, fingerprint, and support status. If unrelated devices all fail, inspect shared layers: coordinator connection, adapter firmware compatibility, host USB stability, Zigbee channel, permit-join state, and interference.

    Do not change the Zigbee channel as an early experiment. Channel changes affect the entire network and sleepy devices may miss the update. First compare Wi-Fi channel use, coordinator placement, packet-loss symptoms, and a controlled short-range retry. If a channel change becomes justified, back up first and follow the official procedure.

    Step 7: clear only the failed partial record

    If Zigbee2MQTT retained an incomplete entry, remove that device entry only, then factory-reset that physical device according to its instructions. Confirm permit-join is enabled for the intended parent and retry once. Do not delete working devices, regenerate the network key, erase the coordinator, or create a new network.

    After removal, verify that the next attempt receives a fresh join event. If no join appears, the device may not have reset, permit-join may have expired, or it may be attempting to rejoin through a parent that is unavailable.

    Step 8: update only with evidence and rollback

    Check the Zigbee2MQTT release notes and supported-device entry before updating. A newer converter may add the fingerprint you need, but updating every component simultaneously destroys the evidence showing which change mattered. Record the current version, preserve the data directory, update one layer, and repeat the same controlled interview.

    Coordinator firmware changes carry greater risk. Confirm the exact adapter hardware, recommended firmware family, backup/restore path, and compatibility with the installed Zigbee stack. Never flash firmware intended for a similar-looking adapter. If the update does not improve the interview, restore the documented supported version when a safe rollback exists.

    Interview versus reconfigure

    An interview discovers what a newly joined device supports. Reconfigure is generally used after a device is already known, to repeat configuration such as binding or reporting where supported. Reconfigure does not replace a missing initial interview and cannot make an unknown fingerprint supported. Use the action that matches the failed stage.

    If the interview completed and the device has correct exposes but updates are missing, reconfigure may be relevant. If the log still says interview failed and the device definition is incomplete, return to wake, link, power, and support checks.

    How to verify a real fix

    • The log explicitly reports a successful interview, not merely a successful join.
    • The device page shows the expected manufacturer, model, endpoints, and exposes.
    • A fresh device-originated state, measurement, or button event appears.
    • One harmless command works where the device supports commands.
    • The device remains available through its normal sleep/report interval.
    • Zigbee2MQTT restarts once and recognizes the device without interviewing it again.

    Validate with a lamp, sensor, or other non-safety-critical device action. Do not use locks, alarms, heaters, medical devices, garage doors, or hazardous loads as the first test.

    Rollback and recovery

    If a software or firmware update worsens the result, stop retrying and restore the prior supported state using its documented rollback process. Restore the Zigbee2MQTT data backup if configuration or device records were damaged. Do not restore an old network key or coordinator backup casually; the coordinator and database must describe the same network.

    If the device joined but no longer responds after being moved, return it to the successful test location, wake it, and allow route repair. If that fails, remove only that device and pair again in the final location. Preserve automations and entity mappings before replacing a device record.

    When to escalate

    Escalate when the exact supported model fails repeatedly at the same interview step with fresh power and a strong link, when multiple devices began failing after a confirmed version change, or when coordinator disconnects appear. Include the device identifiers, Zigbee2MQTT version, coordinator and firmware, channel, installation method, selected pairing parent, wake procedure, and one sanitized debug log from join through failure.

    For a new-device support request, follow the Zigbee2MQTT contributor instructions and provide the exact fingerprint rather than guessing a converter. Do not post network keys, MQTT passwords, tokens, or unnecessary IEEE addresses.

    Prevention

    • Build a stable router backbone before adding many battery devices.
    • Pair devices in or near their intended location when practical.
    • Keep coordinator firmware, Zigbee2MQTT version, and backup dates documented.
    • Retain the manufacturer’s reset and wake instructions for each model.
    • Use fresh batteries for first pairing when the supplied battery is uncertain.
    • Update one layer at a time and test a known-good device afterward.

    What to do when the interview succeeds only beside the coordinator

    A close-range success proves that the device, coordinator, security exchange, and converter can complete an interview under favorable radio conditions. It does not prove the final location has a usable parent path. Do not leave a battery device paired beside the coordinator and simply move it across the home. Remove only that test entry, reset the device, and pair it again in its intended location through a stable mains-powered router when the device supports router-assisted joining.

    If the same device still fails in its final location, compare one known-good device there, confirm the intended router remains powered, and inspect 2.4 GHz interference without changing the whole Zigbee channel immediately. The result distinguishes a placement or parent problem from a model-specific interview problem. Record which parent was used and whether the failure occurs at the same descriptor step; that detail makes escalation much more useful.

    Evidence and testing disclosure

    Applies to: current Zigbee2MQTT installations where a device joins but its interview fails. Expected result: Zigbee2MQTT completes the interview, selects a correct device definition, exposes expected capabilities, and receives a fresh state. Verification: use the explicit successful-interview log plus device-originated and controller-originated tests. Testing status: this guide is based on official Zigbee2MQTT documentation and protocol-layer diagnosis; Troubliq did not physically test every device model. Last reviewed September 29, 2026.

    Related Troubliq guides

    For failures before an interview begins, see the coordinator and serial-port checklist. For ZHA pairing failures, use the ZHA pairing guide. You can also classify a sanitized message with the Home Assistant Error Decoder or browse the Zigbee troubleshooting hub.

  • ZHA coordinator keeps disconnecting with NCP entered failed state

    ZHA coordinator keeps disconnecting with NCP entered failed state

    Direct answer: This message means communication between Home Assistant and a Silicon Labs Zigbee coordinator became unstable. Stabilize the serial connection and power before changing the Zigbee network or re-pairing devices.

    Symptoms

    • ZHA becomes unavailable after startup or at random.
    • Logs contain “NCP entered failed state” or an application-controller restart.
    • Every Zigbee device drops at once.

    Prerequisites

    Record the coordinator model, firmware, connection path, and recent changes. Back up Home Assistant and the Zigbee network if your installation supports it.

    Diagnostic steps

    1. Confirm the coordinator has stable power and a data-capable cable.
    2. Move USB radios onto a short shielded extension cable, away from USB 3 ports and Wi-Fi equipment.
    3. Use a stable /dev/serial/by-id path when Home Assistant runs in a container or VM.
    4. Confirm the host has passed the USB device through to the Home Assistant environment.
    5. Check that ModemManager or another host service is not claiming the serial adapter.
    6. Avoid transporting the EZSP serial connection over Wi-Fi, WAN, or VPN.
    7. Enable ZHA debug logging, reproduce one disconnect, and save the relevant log window.

    Verify the fix

    Restart Home Assistant once, confirm ZHA initializes without errors, then observe whether several mains-powered and battery devices report normally.

    Recovery and rollback

    Do not delete ZHA, erase the radio, or re-pair the mesh while diagnosing a serial transport problem. Revert the cable, port, firmware, or VM mapping change that introduced the failure.

    Prevention

    Keep the coordinator local to the host, use stable device paths, document firmware versions, and change one infrastructure layer at a time.

    Sources

    Last reviewed: September 4, 2026.

    Related Troubliq guides

    Find your next troubleshooting path

    Use the related guide that matches the next confirmed layer of the failure. Avoid changing unrelated systems at the same time.

    Detailed evidence checklist for ZHA coordinator keeps disconnecting with NCP entered failed state

    Before another change, create a short incident record. Include the exact time the symptom appeared, what the system was doing, the last successful action, and every update or network change made during the previous day. Record the Home Assistant release, installation type, integration version, device model, firmware, connection method, current address, and relevant entity IDs. Screenshots are useful for visible states, but copy the exact error text because screenshots may crop the detail needed to search logs.

    Compare the failing item with one known-good item that uses the same path. If both fail, move outward toward shared services such as the integration, coordinator, add-on, DNS, router, cloud account, or Home Assistant host. If only one fails, stay close to that device: power, signal, address, credentials, firmware, permissions, and configuration. This comparison prevents a single-device problem from turning into an unnecessary system-wide rebuild.

    Network tests that prove the failing layer

    Use tests in layers. Confirm the address is current in the router or DHCP server. Confirm the Home Assistant host or container resolves the same name and reaches the intended address. Then test the actual documented service, port, or protocol. A dashboard loading on a phone proves only the phone’s path. A successful ping proves basic reachability, not authentication, WebSocket upgrades, multicast discovery, API encryption, event subscriptions, or application permissions.

    For segmented networks, document source VLAN, destination VLAN, direction, protocol, and port before editing a firewall rule. Test the smallest temporary exception and remove it if it did not help. Discovery traffic and control traffic may use different mechanisms. Seeing a device in discovery does not prove Home Assistant can maintain a working session.

    Configuration comparison procedure

    Export or photograph the current configuration without exposing secrets. Compare it with official documentation field by field: host, port, account, region, project, encryption setting, device identifier, and optional switches. Watch for trailing spaces, uppercase versus lowercase account names, obsolete hostnames, restored encryption keys, or an account belonging to the wrong home or region.

    Use Reconfigure or Reauthenticate before deleting an integration. Preserve entity IDs and note every automation, dashboard, script, scene, or helper that refers to them. If replacement becomes necessary, take a backup and map old entities to replacements. That makes rollback controlled rather than leaving broken references.

    Power, radio, and timing checks

    Do not interpret every unavailable state as software failure. Low-voltage devices may stay partly online while unstable power causes resets. Battery devices sleep and report on their own schedule. Wi-Fi and Bluetooth devices can associate yet fail at the application layer. Zigbee and Z-Wave devices depend on routes, radio conditions, and powered repeaters. Match the test to the technology instead of repeatedly pressing Reload.

    Allow enough time after each test. Cloud polling, sleepy devices, retained MQTT messages, mesh repair, Bluetooth advertisements, and DHCP changes do not update instantly. Define the expected interval, then wait through at least two normal cycles. If availability returns briefly, capture the next disconnect in logs instead of declaring success.

    Log-reading workflow

    Synchronize clocks and reproduce the problem once. Start with the first warning or error at that timestamp; later messages may be consequences. Group errors by layer: name resolution, timeout, refused connection, TLS certificate, unauthorized account, invalid token, missing permission, unsupported capability, malformed payload, device timeout, or rate limit. Each group suggests a different next action.

    Turn debug logging off after reproduction. Large files consume storage and bury the event. Redact tokens, passwords, keys, email addresses, public addresses, precise locations, and unnecessary unique identifiers. Keep the unredacted copy private for comparison with later tests.

    Safe change order

    1. Correct time, power, cabling, or an obviously stale address.
    2. Reload only the affected integration when documentation supports it.
    3. Use Reconfigure or Reauthenticate without deleting the entry.
    4. Restart only the affected device or add-on during a safe window.
    5. Restart Home Assistant when several components share the symptom or a change requires it.
    6. Update software after reading release notes and preserving rollback.
    7. Delete, exclude, reset, or rebuild only after safer checks prove it necessary.

    Post-repair validation

    Verify both directions. Confirm Home Assistant receives a fresh state, send one harmless command, and confirm the physical response. Check the returned state, logbook, history, and automation trace. Restart the affected component and verify automatic reconnection. During a maintenance window, confirm the repair survives a normal Home Assistant restart.

    Monitor long enough to cover the original pattern. If failure occurred overnight, after DHCP renewal, deep sleep, or token expiry, a five-minute test is insufficient. Record the confirmed cause and exact corrective change. Remove temporary firewall rules, extra logging, duplicate test integrations, and unused credentials.

    When to stop and escalate

    Stop if hardware overheats, power is unstable, storage reports errors, a controller backup fails, credentials are rejected across services, or firmware may be damaged. Escalate with versions, timestamps, topology, redacted logs, the first meaningful error, and results of each safe test. Do not repeat destructive steps while waiting for help.

    A strong report answers four questions: What still works? What exactly fails? What changed immediately beforehand? Which test most clearly separates the causes? Those answers help maintainers diagnose the correct layer.

    Verification checkpoint 1 focuses on stable by-id path. Observe the relevant state, event or log through two normal cycles and write down the timestamp. If the result is unchanged, undo the experimental change before testing another layer so the diagnosis remains controlled and reversible.Validation note 1: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    For checkpoint 2, inspect USB power rather than relying on the dashboard icon alone. Confirm the expected input, the system response and the returned state. Preserve the evidence, reverse any ineffective adjustment and move to the next checkpoint only after the current result is clear.Validation note 2: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Checkpoint 3 — host detection: reproduce the original symptom once and record the result at the expected update interval. Compare it with the last known-good behavior. Keep the change only when this specific checkpoint improves the failure without creating a new warning; otherwise restore the previous value.Validation note 3: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Verification checkpoint 4 focuses on radio type. Observe the relevant state, event or log through two normal cycles and write down the timestamp. If the result is unchanged, undo the experimental change before testing another layer so the diagnosis remains controlled and reversible.Validation note 4: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    For checkpoint 5, inspect serial ownership rather than relying on the dashboard icon alone. Confirm the expected input, the system response and the returned state. Preserve the evidence, reverse any ineffective adjustment and move to the next checkpoint only after the current result is clear.Validation note 5: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Checkpoint 6 — container passthrough: reproduce the original symptom once and record the result at the expected update interval. Compare it with the last known-good behavior. Keep the change only when this specific checkpoint improves the failure without creating a new warning; otherwise restore the previous value.Validation note 6: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Verification checkpoint 7 focuses on adapter firmware. Observe the relevant state, event or log through two normal cycles and write down the timestamp. If the result is unchanged, undo the experimental change before testing another layer so the diagnosis remains controlled and reversible.Validation note 7: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    For checkpoint 8, inspect extension-cable placement rather than relying on the dashboard icon alone. Confirm the expected input, the system response and the returned state. Preserve the evidence, reverse any ineffective adjustment and move to the next checkpoint only after the current result is clear.Validation note 8: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Checkpoint 9 — initialization trace: reproduce the original symptom once and record the result at the expected update interval. Compare it with the last known-good behavior. Keep the change only when this specific checkpoint improves the failure without creating a new warning; otherwise restore the previous value.Validation note 9: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Verification checkpoint 10 focuses on network backup. Observe the relevant state, event or log through two normal cycles and write down the timestamp. If the result is unchanged, undo the experimental change before testing another layer so the diagnosis remains controlled and reversible.Validation note 10: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    For checkpoint 11, inspect restart persistence rather than relying on the dashboard icon alone. Confirm the expected input, the system response and the returned state. Preserve the evidence, reverse any ineffective adjustment and move to the next checkpoint only after the current result is clear.Validation note 11: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Identify what “NCP failed” means for this coordinator

    NCP refers to the network coprocessor used by many Zigbee coordinators. A failed state can come from a missing serial device, another process holding the port, an incorrect radio type, unstable USB power, firmware trouble or a coordinator that is still booting. Record the coordinator model, chipset, firmware, connection type and the exact ZHA initialization error before changing the configuration.

    For USB coordinators, use the stable by-id device path rather than a changing ttyUSB or ttyACM number. Confirm that the host still detects the adapter after a full power cycle and that the device has not been passed to another container, add-on or virtual machine. Zigbee2MQTT and ZHA must not open the same coordinator simultaneously. For network coordinators, verify the documented socket address and confirm that only the intended Zigbee service is using it.

    Check power and USB behavior safely

    Move the coordinator away from USB 3 ports, storage devices and Wi-Fi radios using a quality extension cable. Inspect host logs for disconnects or resets. Do not flash firmware simply because initialization failed once. First rule out a loose connector, inadequate power, a changed device path and a second process holding the serial interface.

    If firmware work becomes necessary, export a Home Assistant backup and preserve the Zigbee network information supported by the adapter and ZHA. Confirm the firmware image matches the exact chipset and bootloader. An incorrect image can make the coordinator unavailable and may prevent network recovery.

    Prove that the Zigbee network recovered

    • ZHA initializes without repeated radio or serial errors.
    • The coordinator remains connected through a normal Home Assistant restart.
    • Existing routers and end devices return without creating duplicates.
    • A nearby device reports a fresh attribute and accepts one harmless command.
    • No other add-on or container opens the coordinator port.

    If ZHA cannot start but the operating system sees the adapter consistently, collect the full initialization trace and compare its protocol and baud settings with the adapter documentation. If the adapter disappears at the operating-system level, focus on hardware, USB passthrough and power rather than repeatedly reloading ZHA.

  • Home Assistant Energy dashboard sensor is missing from the selection list

    Home Assistant Energy dashboard sensor is missing from the selection list

    Direct answer: The Energy dashboard only offers compatible sensor entities. Check the entity domain, device class, state class, unit, and long-term statistics errors before changing the dashboard.

    Symptoms

    • A working power or energy entity is absent from the Energy dashboard selector.
    • The entity appears elsewhere but cannot be chosen for grid, solar, battery, gas, or water.

    Prerequisites

    Record the entity ID and current attributes. Do not edit recorder data or entity registries as a first step.

    Diagnostic steps

    1. Open Settings → Developer tools → States and find the entity.
    2. Confirm it belongs to the sensor domain.
    3. Check device_class: electricity normally requires energy or power; gas and water require their matching classes.
    4. Check state_class. Power measurements normally use measurement; accumulated energy normally uses total or total_increasing.
    5. Confirm the unit is supported and correctly written.
    6. Open Settings → Developer tools → Statistics and resolve any issue shown for the entity.
    7. If an integration supplies incorrect attributes, update it and report the problem to that integration rather than masking it blindly.

    Verify the fix

    After valid statistics are generated, reopen Energy configuration and confirm the sensor appears. Add it, then verify new readings and totals rather than relying on the selector alone.

    Recovery and rollback

    If you created a template sensor, keep the original entity unchanged until the replacement has accumulated valid data. Remove the template only after reverting the dashboard selection.

    Prevention

    Prefer integration-provided energy entities, document templates, and check Statistics after unit or firmware changes.

    Sources

    Last reviewed: September 4, 2026.

    Related Troubliq guides

    Find your next troubleshooting path

    Use the related guide that matches the next confirmed layer of the failure. Avoid changing unrelated systems at the same time.

    Detailed evidence checklist for Home Assistant Energy dashboard sensor is missing from the selection list

    Before another change, create a short incident record. Include the exact time the symptom appeared, what the system was doing, the last successful action, and every update or network change made during the previous day. Record the Home Assistant release, installation type, integration version, device model, firmware, connection method, current address, and relevant entity IDs. Screenshots are useful for visible states, but copy the exact error text because screenshots may crop the detail needed to search logs.

    Compare the failing item with one known-good item that uses the same path. If both fail, move outward toward shared services such as the integration, coordinator, add-on, DNS, router, cloud account, or Home Assistant host. If only one fails, stay close to that device: power, signal, address, credentials, firmware, permissions, and configuration. This comparison prevents a single-device problem from turning into an unnecessary system-wide rebuild.

    Network tests that prove the failing layer

    Use tests in layers. Confirm the address is current in the router or DHCP server. Confirm the Home Assistant host or container resolves the same name and reaches the intended address. Then test the actual documented service, port, or protocol. A dashboard loading on a phone proves only the phone’s path. A successful ping proves basic reachability, not authentication, WebSocket upgrades, multicast discovery, API encryption, event subscriptions, or application permissions.

    For segmented networks, document source VLAN, destination VLAN, direction, protocol, and port before editing a firewall rule. Test the smallest temporary exception and remove it if it did not help. Discovery traffic and control traffic may use different mechanisms. Seeing a device in discovery does not prove Home Assistant can maintain a working session.

    Configuration comparison procedure

    Export or photograph the current configuration without exposing secrets. Compare it with official documentation field by field: host, port, account, region, project, encryption setting, device identifier, and optional switches. Watch for trailing spaces, uppercase versus lowercase account names, obsolete hostnames, restored encryption keys, or an account belonging to the wrong home or region.

    Use Reconfigure or Reauthenticate before deleting an integration. Preserve entity IDs and note every automation, dashboard, script, scene, or helper that refers to them. If replacement becomes necessary, take a backup and map old entities to replacements. That makes rollback controlled rather than leaving broken references.

    Power, radio, and timing checks

    Do not interpret every unavailable state as software failure. Low-voltage devices may stay partly online while unstable power causes resets. Battery devices sleep and report on their own schedule. Wi-Fi and Bluetooth devices can associate yet fail at the application layer. Zigbee and Z-Wave devices depend on routes, radio conditions, and powered repeaters. Match the test to the technology instead of repeatedly pressing Reload.

    Allow enough time after each test. Cloud polling, sleepy devices, retained MQTT messages, mesh repair, Bluetooth advertisements, and DHCP changes do not update instantly. Define the expected interval, then wait through at least two normal cycles. If availability returns briefly, capture the next disconnect in logs instead of declaring success.

    Log-reading workflow

    Synchronize clocks and reproduce the problem once. Start with the first warning or error at that timestamp; later messages may be consequences. Group errors by layer: name resolution, timeout, refused connection, TLS certificate, unauthorized account, invalid token, missing permission, unsupported capability, malformed payload, device timeout, or rate limit. Each group suggests a different next action.

    Turn debug logging off after reproduction. Large files consume storage and bury the event. Redact tokens, passwords, keys, email addresses, public addresses, precise locations, and unnecessary unique identifiers. Keep the unredacted copy private for comparison with later tests.

    Safe change order

    1. Correct time, power, cabling, or an obviously stale address.
    2. Reload only the affected integration when documentation supports it.
    3. Use Reconfigure or Reauthenticate without deleting the entry.
    4. Restart only the affected device or add-on during a safe window.
    5. Restart Home Assistant when several components share the symptom or a change requires it.
    6. Update software after reading release notes and preserving rollback.
    7. Delete, exclude, reset, or rebuild only after safer checks prove it necessary.

    Post-repair validation

    Verify both directions. Confirm Home Assistant receives a fresh state, send one harmless command, and confirm the physical response. Check the returned state, logbook, history, and automation trace. Restart the affected component and verify automatic reconnection. During a maintenance window, confirm the repair survives a normal Home Assistant restart.

    Monitor long enough to cover the original pattern. If failure occurred overnight, after DHCP renewal, deep sleep, or token expiry, a five-minute test is insufficient. Record the confirmed cause and exact corrective change. Remove temporary firewall rules, extra logging, duplicate test integrations, and unused credentials.

    When to stop and escalate

    Stop if hardware overheats, power is unstable, storage reports errors, a controller backup fails, credentials are rejected across services, or firmware may be damaged. Escalate with versions, timestamps, topology, redacted logs, the first meaningful error, and results of each safe test. Do not repeat destructive steps while waiting for help.

    A strong report answers four questions: What still works? What exactly fails? What changed immediately beforehand? Which test most clearly separates the causes? Those answers help maintainers diagnose the correct layer.

    For checkpoint 1, inspect measurement unit rather than relying on the dashboard icon alone. Confirm the expected input, the system response and the returned state. Preserve the evidence, reverse any ineffective adjustment and move to the next checkpoint only after the current result is clear.Validation note 1: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Checkpoint 2 — device class: reproduce the original symptom once and record the result at the expected update interval. Compare it with the last known-good behavior. Keep the change only when this specific checkpoint improves the failure without creating a new warning; otherwise restore the previous value.Validation note 2: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Verification checkpoint 3 focuses on state class. Observe the relevant state, event or log through two normal cycles and write down the timestamp. If the result is unchanged, undo the experimental change before testing another layer so the diagnosis remains controlled and reversible.Validation note 3: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    For checkpoint 4, inspect numeric state rather than relying on the dashboard icon alone. Confirm the expected input, the system response and the returned state. Preserve the evidence, reverse any ineffective adjustment and move to the next checkpoint only after the current result is clear.Validation note 4: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Checkpoint 5 — statistics ID: reproduce the original symptom once and record the result at the expected update interval. Compare it with the last known-good behavior. Keep the change only when this specific checkpoint improves the failure without creating a new warning; otherwise restore the previous value.Validation note 5: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Verification checkpoint 6 focuses on statistics repair. Observe the relevant state, event or log through two normal cycles and write down the timestamp. If the result is unchanged, undo the experimental change before testing another layer so the diagnosis remains controlled and reversible.Validation note 6: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    For checkpoint 7, inspect power integration helper rather than relying on the dashboard icon alone. Confirm the expected input, the system response and the returned state. Preserve the evidence, reverse any ineffective adjustment and move to the next checkpoint only after the current result is clear.Validation note 7: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Checkpoint 8 — utility-meter source: reproduce the original symptom once and record the result at the expected update interval. Compare it with the last known-good behavior. Keep the change only when this specific checkpoint improves the failure without creating a new warning; otherwise restore the previous value.Validation note 8: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Verification checkpoint 9 focuses on metric prefix. Observe the relevant state, event or log through two normal cycles and write down the timestamp. If the result is unchanged, undo the experimental change before testing another layer so the diagnosis remains controlled and reversible.Validation note 9: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    For checkpoint 10, inspect dashboard refresh rather than relying on the dashboard icon alone. Confirm the expected input, the system response and the returned state. Preserve the evidence, reverse any ineffective adjustment and move to the next checkpoint only after the current result is clear.Validation note 10: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Checkpoint 11 — controlled-load comparison: reproduce the original symptom once and record the result at the expected update interval. Compare it with the last known-good behavior. Keep the change only when this specific checkpoint improves the failure without creating a new warning; otherwise restore the previous value.Validation note 11: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Confirm that the entity qualifies for the Energy dashboard

    The Energy dashboard does not list every sensor that displays watts or kilowatt-hours. A consumption source normally needs a supported device class, an appropriate state class and a cumulative energy unit such as Wh or kWh. Open Developer Tools, inspect the entity and record its unit, device_class, state_class and current state. A power sensor measured in W describes a rate; it must be integrated over time before it can represent energy.

    For a cumulative meter, determine whether it increases continuously, resets periodically or can decrease. Use the state class that matches the sensor’s real behavior rather than forcing metadata solely to make the entity appear. Incorrect statistics metadata can produce misleading totals and long-term-statistics warnings.

    Check statistics before editing helpers

    Open Developer Tools and the statistics repair interface. Look for unit changes, unsupported units, non-numeric states, duplicate statistic IDs or a discontinuity caused by replacing an entity. Correct the upstream sensor when possible. A template or utility meter can be appropriate, but it should have a clearly documented source and should not duplicate an already valid cumulative reading.

    If the source is instantaneous power, create an integration helper using the correct time unit and metric prefix, then allow it to accumulate before selecting it. If a daily or monthly view is needed, create a Utility Meter from a valid cumulative energy sensor. Do not chain helpers without checking the resulting unit and statistics behavior.

    Verify the dashboard data path

    • The entity exposes a numeric state in Wh or kWh.
    • Its device and state classes match the measurement behavior.
    • Long-term statistics appear without repair warnings.
    • The Energy configuration accepts the entity after statistics refresh.
    • Totals increase plausibly when a known load operates.

    Allow enough time for the statistics cycle; the dashboard is not an instantaneous display. Compare a controlled appliance run with the change in the cumulative sensor and the dashboard total. If the value is off by a factor of 1,000, inspect unit conversion and metric-prefix settings instead of compensating with an arbitrary dashboard adjustment.

  • Thread credentials are synced but Matter commissioning still fails in Home Assistant

    Thread credentials are synced but Matter commissioning still fails in Home Assistant

    Direct answer: Confirm that Home Assistant knows the selected Thread network credentials, that the phone has the same credentials, and that IPv6 and local discovery work between Home Assistant, the phone, and the border router.

    Symptoms

    • Commissioning times out after scanning the Matter code.
    • The app says a Thread border router is required even though one is running.
    • Home Assistant and the phone prefer different Thread networks.

    Prerequisites

    Update Home Assistant and its Companion app, enable Bluetooth on the phone, place the device in pairing mode, and keep the phone on the same local Wi-Fi as the border router.

    Diagnostic steps

    1. Open Settings → Devices & services → Thread → Configure.
    2. Identify the preferred network. Home Assistant can only prefer a network whose credentials it knows.
    3. In the Companion app, use its Thread credential sync or send-credentials action for your platform.
    4. Reopen the Thread panel and confirm Home Assistant and the phone reference the same network.
    5. Check the OpenThread Border Router app status and logs.
    6. Verify IPv6 works on the Home Assistant host, router, and any container or VM layer.
    7. Return the device to pairing mode and retry nearby.

    Verify the fix

    The device should finish commissioning, appear under Matter, respond to a command, and remain reachable after several minutes.

    Recovery and rollback

    Do not delete Thread datasets or reset border routers as an early step. Those actions can strand existing devices. If retrying, remove only the failed partial device entry and follow the manufacturer’s pairing-mode instructions.

    Prevention

    Choose one preferred Thread network intentionally, keep credential copies synchronized, and document which border routers belong to it.

    Video overview: understand Matter’s network requirements

    Vaclav Chaloupka explains the moving parts behind Matter in Home Assistant and shows the commissioning flow. The overview is especially helpful for understanding why the phone, Home Assistant host, Thread border router, local IPv6 network, and shared credentials must all agree before a Matter-over-Thread device can join reliably.

    Video: “Matter in Home Assistant: It is dead simple (if you know how — explained in the video)” by Vaclav Chaloupka. Embedded from the creator’s original YouTube upload.

    Sources

    Last reviewed: September 4, 2026.

    Related Troubliq guides

    Find your next troubleshooting path

    Use the related guide that matches the next confirmed layer of the failure. Avoid changing unrelated systems at the same time.

    Detailed evidence checklist for Thread credentials are synced but Matter commissioning still fails in Home Assistant

    Before another change, create a short incident record. Include the exact time the symptom appeared, what the system was doing, the last successful action, and every update or network change made during the previous day. Record the Home Assistant release, installation type, integration version, device model, firmware, connection method, current address, and relevant entity IDs. Screenshots are useful for visible states, but copy the exact error text because screenshots may crop the detail needed to search logs.

    Compare the failing item with one known-good item that uses the same path. If both fail, move outward toward shared services such as the integration, coordinator, add-on, DNS, router, cloud account, or Home Assistant host. If only one fails, stay close to that device: power, signal, address, credentials, firmware, permissions, and configuration. This comparison prevents a single-device problem from turning into an unnecessary system-wide rebuild.

    Network tests that prove the failing layer

    Use tests in layers. Confirm the address is current in the router or DHCP server. Confirm the Home Assistant host or container resolves the same name and reaches the intended address. Then test the actual documented service, port, or protocol. A dashboard loading on a phone proves only the phone’s path. A successful ping proves basic reachability, not authentication, WebSocket upgrades, multicast discovery, API encryption, event subscriptions, or application permissions.

    For segmented networks, document source VLAN, destination VLAN, direction, protocol, and port before editing a firewall rule. Test the smallest temporary exception and remove it if it did not help. Discovery traffic and control traffic may use different mechanisms. Seeing a device in discovery does not prove Home Assistant can maintain a working session.

    Configuration comparison procedure

    Export or photograph the current configuration without exposing secrets. Compare it with official documentation field by field: host, port, account, region, project, encryption setting, device identifier, and optional switches. Watch for trailing spaces, uppercase versus lowercase account names, obsolete hostnames, restored encryption keys, or an account belonging to the wrong home or region.

    Use Reconfigure or Reauthenticate before deleting an integration. Preserve entity IDs and note every automation, dashboard, script, scene, or helper that refers to them. If replacement becomes necessary, take a backup and map old entities to replacements. That makes rollback controlled rather than leaving broken references.

    Power, radio, and timing checks

    Do not interpret every unavailable state as software failure. Low-voltage devices may stay partly online while unstable power causes resets. Battery devices sleep and report on their own schedule. Wi-Fi and Bluetooth devices can associate yet fail at the application layer. Zigbee and Z-Wave devices depend on routes, radio conditions, and powered repeaters. Match the test to the technology instead of repeatedly pressing Reload.

    Allow enough time after each test. Cloud polling, sleepy devices, retained MQTT messages, mesh repair, Bluetooth advertisements, and DHCP changes do not update instantly. Define the expected interval, then wait through at least two normal cycles. If availability returns briefly, capture the next disconnect in logs instead of declaring success.

    Log-reading workflow

    Synchronize clocks and reproduce the problem once. Start with the first warning or error at that timestamp; later messages may be consequences. Group errors by layer: name resolution, timeout, refused connection, TLS certificate, unauthorized account, invalid token, missing permission, unsupported capability, malformed payload, device timeout, or rate limit. Each group suggests a different next action.

    Turn debug logging off after reproduction. Large files consume storage and bury the event. Redact tokens, passwords, keys, email addresses, public addresses, precise locations, and unnecessary unique identifiers. Keep the unredacted copy private for comparison with later tests.

    Safe change order

    1. Correct time, power, cabling, or an obviously stale address.
    2. Reload only the affected integration when documentation supports it.
    3. Use Reconfigure or Reauthenticate without deleting the entry.
    4. Restart only the affected device or add-on during a safe window.
    5. Restart Home Assistant when several components share the symptom or a change requires it.
    6. Update software after reading release notes and preserving rollback.
    7. Delete, exclude, reset, or rebuild only after safer checks prove it necessary.

    Post-repair validation

    Verify both directions. Confirm Home Assistant receives a fresh state, send one harmless command, and confirm the physical response. Check the returned state, logbook, history, and automation trace. Restart the affected component and verify automatic reconnection. During a maintenance window, confirm the repair survives a normal Home Assistant restart.

    Monitor long enough to cover the original pattern. If failure occurred overnight, after DHCP renewal, deep sleep, or token expiry, a five-minute test is insufficient. Record the confirmed cause and exact corrective change. Remove temporary firewall rules, extra logging, duplicate test integrations, and unused credentials.

    When to stop and escalate

    Stop if hardware overheats, power is unstable, storage reports errors, a controller backup fails, credentials are rejected across services, or firmware may be damaged. Escalate with versions, timestamps, topology, redacted logs, the first meaningful error, and results of each safe test. Do not repeat destructive steps while waiting for help.

    A strong report answers four questions: What still works? What exactly fails? What changed immediately beforehand? Which test most clearly separates the causes? Those answers help maintainers diagnose the correct layer.

    Checkpoint 1 — preferred Thread dataset: reproduce the original symptom once and record the result at the expected update interval. Compare it with the last known-good behavior. Keep the change only when this specific checkpoint improves the failure without creating a new warning; otherwise restore the previous value.Validation note 1: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Verification checkpoint 2 focuses on phone credentials. Observe the relevant state, event or log through two normal cycles and write down the timestamp. If the result is unchanged, undo the experimental change before testing another layer so the diagnosis remains controlled and reversible.Validation note 2: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    For checkpoint 3, inspect Bluetooth handoff rather than relying on the dashboard icon alone. Confirm the expected input, the system response and the returned state. Preserve the evidence, reverse any ineffective adjustment and move to the next checkpoint only after the current result is clear.Validation note 3: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Checkpoint 4 — Matter server: reproduce the original symptom once and record the result at the expected update interval. Compare it with the last known-good behavior. Keep the change only when this specific checkpoint improves the failure without creating a new warning; otherwise restore the previous value.Validation note 4: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Verification checkpoint 5 focuses on border router. Observe the relevant state, event or log through two normal cycles and write down the timestamp. If the result is unchanged, undo the experimental change before testing another layer so the diagnosis remains controlled and reversible.Validation note 5: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    For checkpoint 6, inspect local IPv6 rather than relying on the dashboard icon alone. Confirm the expected input, the system response and the returned state. Preserve the evidence, reverse any ineffective adjustment and move to the next checkpoint only after the current result is clear.Validation note 6: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Checkpoint 7 — multicast discovery: reproduce the original symptom once and record the result at the expected update interval. Compare it with the last known-good behavior. Keep the change only when this specific checkpoint improves the failure without creating a new warning; otherwise restore the previous value.Validation note 7: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Verification checkpoint 8 focuses on fabric membership. Observe the relevant state, event or log through two normal cycles and write down the timestamp. If the result is unchanged, undo the experimental change before testing another layer so the diagnosis remains controlled and reversible.Validation note 8: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    For checkpoint 9, inspect multi-admin sharing rather than relying on the dashboard icon alone. Confirm the expected input, the system response and the returned state. Preserve the evidence, reverse any ineffective adjustment and move to the next checkpoint only after the current result is clear.Validation note 9: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Checkpoint 10 — commissioning logs: reproduce the original symptom once and record the result at the expected update interval. Compare it with the last known-good behavior. Keep the change only when this specific checkpoint improves the failure without creating a new warning; otherwise restore the previous value.Validation note 10: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Verification checkpoint 11 focuses on restart persistence. Observe the relevant state, event or log through two normal cycles and write down the timestamp. If the result is unchanged, undo the experimental change before testing another layer so the diagnosis remains controlled and reversible.Validation note 11: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Map the commissioning path before resetting the device

    Matter commissioning can involve the phone, Home Assistant Companion app, Matter server, border router, Thread credentials, Bluetooth and the local IPv6 network. Identify which component owns the preferred Thread network and whether the phone has received the same operational dataset. Seeing credentials in one interface does not prove that the commissioning phone, Matter server and border router are using the same dataset.

    Confirm Bluetooth is enabled for the initial handoff, the phone is on the intended LAN and required app permissions are granted. Keep the phone and device near the border router during the test. Do not disable IPv6: Matter relies on IPv6 locally even when the internet connection is primarily IPv4.

    Distinguish a Thread attachment failure from a fabric failure

    If commissioning fails before the device joins Thread, examine border-router availability, dataset consistency and radio reachability. If the device joins Thread but cannot be added to Home Assistant, examine Matter-server logs, fabric state, multicast reachability and whether the device is already commissioned to another fabric. Multi-admin sharing should use the existing ecosystem’s share flow; repeatedly factory-resetting a working device can create stale entries without repairing the network.

    On segmented networks, confirm the phone, Home Assistant, Matter server and border-router discovery traffic can cross only the required trusted boundaries. Avoid broad firewall exceptions. Capture the timestamp of one commissioning attempt and align the Companion app, Matter server and border-router logs.

    Verify a durable Matter repair

    • The device appears once on the intended Matter fabric.
    • The Matter server reports the node as available after commissioning.
    • Commands and state updates work after Bluetooth is turned off.
    • The device survives a normal restart of Home Assistant and the Matter server.
    • Thread diagnostics show attachment to the intended network.

    If another ecosystem already controls the device, test its official multi-admin sharing procedure before erasing it. Record the device model, firmware, border-router model, Thread dataset source, Companion app platform and the precise commissioning stage that fails. Those facts determine whether the next investigation belongs in Thread transport, Matter fabric management or the vendor implementation.

  • Z-Wave JS node is dead or unavailable in Home Assistant: recovery checklist

    Z-Wave JS node is dead or unavailable in Home Assistant: recovery checklist

    Direct answer: A Z-Wave node marked dead or unavailable is usually failing to answer the controller. Check power, controller connectivity, USB interference, and the mesh route before excluding or factory-resetting it.

    Symptoms

    • The device card is unavailable.
    • The Z-Wave node-status sensor reports dead.
    • Commands time out or updates arrive intermittently.

    Before you start

    Do not remove the integration, reset the controller, or factory-reset the device. Preserve your Z-Wave security keys and create a backup before any destructive recovery.

    Diagnostic steps

    1. Confirm the device has power. For battery devices, install a known-good battery and wake the device using its manual.
    2. Open Settings → Devices & services → Z-Wave and confirm the integration and Z-Wave JS server are connected.
    3. Open the device and inspect its node status and communication statistics.
    4. If the adapter is connected directly to USB, move it to a short USB extension cable to reduce RF interference.
    5. For a mains-powered node, use the Ping button once. Battery devices normally sleep, so pinging them while asleep proves little.
    6. After correcting power or interference, rebuild routes where the interface offers that action. Allow the mesh time to settle.
    7. Enable debug logging briefly and reproduce the failure. Download diagnostics before escalating.

    Verify the fix

    Send one command, confirm the physical device responds, and check that a new state report returns to Home Assistant. Watch the node statistics for repeated failures.

    Recovery and rollback

    If the device remains dead, consult its manufacturer instructions and the current Z-Wave JS documentation before exclusion or replacement. Exclusion and factory reset can break entity references and automations, so treat them as last-resort steps.

    Prevention

    Keep the adapter away from USB 3 interference, use stable device paths for external servers, retain security-key backups, and build a healthy mains-powered mesh.

    Sources

    Last reviewed: September 4, 2026.

    Related Troubliq guides

    Find your next troubleshooting path

    Use the related guide that matches the next confirmed layer of the failure. Avoid changing unrelated systems at the same time.

    Detailed evidence checklist for Z-Wave JS node is dead or unavailable in Home Assistant

    Before another change, create a short incident record. Include the exact time the symptom appeared, what the system was doing, the last successful action, and every update or network change made during the previous day. Record the Home Assistant release, installation type, integration version, device model, firmware, connection method, current address, and relevant entity IDs. Screenshots are useful for visible states, but copy the exact error text because screenshots may crop the detail needed to search logs.

    Compare the failing item with one known-good item that uses the same path. If both fail, move outward toward shared services such as the integration, coordinator, add-on, DNS, router, cloud account, or Home Assistant host. If only one fails, stay close to that device: power, signal, address, credentials, firmware, permissions, and configuration. This comparison prevents a single-device problem from turning into an unnecessary system-wide rebuild.

    Network tests that prove the failing layer

    Use tests in layers. Confirm the address is current in the router or DHCP server. Confirm the Home Assistant host or container resolves the same name and reaches the intended address. Then test the actual documented service, port, or protocol. A dashboard loading on a phone proves only the phone’s path. A successful ping proves basic reachability, not authentication, WebSocket upgrades, multicast discovery, API encryption, event subscriptions, or application permissions.

    For segmented networks, document source VLAN, destination VLAN, direction, protocol, and port before editing a firewall rule. Test the smallest temporary exception and remove it if it did not help. Discovery traffic and control traffic may use different mechanisms. Seeing a device in discovery does not prove Home Assistant can maintain a working session.

    Configuration comparison procedure

    Export or photograph the current configuration without exposing secrets. Compare it with official documentation field by field: host, port, account, region, project, encryption setting, device identifier, and optional switches. Watch for trailing spaces, uppercase versus lowercase account names, obsolete hostnames, restored encryption keys, or an account belonging to the wrong home or region.

    Use Reconfigure or Reauthenticate before deleting an integration. Preserve entity IDs and note every automation, dashboard, script, scene, or helper that refers to them. If replacement becomes necessary, take a backup and map old entities to replacements. That makes rollback controlled rather than leaving broken references.

    Power, radio, and timing checks

    Do not interpret every unavailable state as software failure. Low-voltage devices may stay partly online while unstable power causes resets. Battery devices sleep and report on their own schedule. Wi-Fi and Bluetooth devices can associate yet fail at the application layer. Zigbee and Z-Wave devices depend on routes, radio conditions, and powered repeaters. Match the test to the technology instead of repeatedly pressing Reload.

    Allow enough time after each test. Cloud polling, sleepy devices, retained MQTT messages, mesh repair, Bluetooth advertisements, and DHCP changes do not update instantly. Define the expected interval, then wait through at least two normal cycles. If availability returns briefly, capture the next disconnect in logs instead of declaring success.

    Log-reading workflow

    Synchronize clocks and reproduce the problem once. Start with the first warning or error at that timestamp; later messages may be consequences. Group errors by layer: name resolution, timeout, refused connection, TLS certificate, unauthorized account, invalid token, missing permission, unsupported capability, malformed payload, device timeout, or rate limit. Each group suggests a different next action.

    Turn debug logging off after reproduction. Large files consume storage and bury the event. Redact tokens, passwords, keys, email addresses, public addresses, precise locations, and unnecessary unique identifiers. Keep the unredacted copy private for comparison with later tests.

    Safe change order

    1. Correct time, power, cabling, or an obviously stale address.
    2. Reload only the affected integration when documentation supports it.
    3. Use Reconfigure or Reauthenticate without deleting the entry.
    4. Restart only the affected device or add-on during a safe window.
    5. Restart Home Assistant when several components share the symptom or a change requires it.
    6. Update software after reading release notes and preserving rollback.
    7. Delete, exclude, reset, or rebuild only after safer checks prove it necessary.

    Post-repair validation

    Verify both directions. Confirm Home Assistant receives a fresh state, send one harmless command, and confirm the physical response. Check the returned state, logbook, history, and automation trace. Restart the affected component and verify automatic reconnection. During a maintenance window, confirm the repair survives a normal Home Assistant restart.

    Monitor long enough to cover the original pattern. If failure occurred overnight, after DHCP renewal, deep sleep, or token expiry, a five-minute test is insufficient. Record the confirmed cause and exact corrective change. Remove temporary firewall rules, extra logging, duplicate test integrations, and unused credentials.

    When to stop and escalate

    Stop if hardware overheats, power is unstable, storage reports errors, a controller backup fails, credentials are rejected across services, or firmware may be damaged. Escalate with versions, timestamps, topology, redacted logs, the first meaningful error, and results of each safe test. Do not repeat destructive steps while waiting for help.

    A strong report answers four questions: What still works? What exactly fails? What changed immediately beforehand? Which test most clearly separates the causes? Those answers help maintainers diagnose the correct layer.

    Verification checkpoint 1 focuses on power source. Observe the relevant state, event or log through two normal cycles and write down the timestamp. If the result is unchanged, undo the experimental change before testing another layer so the diagnosis remains controlled and reversible.Validation note 1: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    For checkpoint 2, inspect wake interval rather than relying on the dashboard icon alone. Confirm the expected input, the system response and the returned state. Preserve the evidence, reverse any ineffective adjustment and move to the next checkpoint only after the current result is clear.Validation note 2: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Checkpoint 3 — last-seen time: reproduce the original symptom once and record the result at the expected update interval. Compare it with the last known-good behavior. Keep the change only when this specific checkpoint improves the failure without creating a new warning; otherwise restore the previous value.Validation note 3: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Verification checkpoint 4 focuses on command queue. Observe the relevant state, event or log through two normal cycles and write down the timestamp. If the result is unchanged, undo the experimental change before testing another layer so the diagnosis remains controlled and reversible.Validation note 4: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    For checkpoint 5, inspect route statistics rather than relying on the dashboard icon alone. Confirm the expected input, the system response and the returned state. Preserve the evidence, reverse any ineffective adjustment and move to the next checkpoint only after the current result is clear.Validation note 5: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Checkpoint 6 — powered repeaters: reproduce the original symptom once and record the result at the expected update interval. Compare it with the last known-good behavior. Keep the change only when this specific checkpoint improves the failure without creating a new warning; otherwise restore the previous value.Validation note 6: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Verification checkpoint 7 focuses on individual heal. Observe the relevant state, event or log through two normal cycles and write down the timestamp. If the result is unchanged, undo the experimental change before testing another layer so the diagnosis remains controlled and reversible.Validation note 7: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    For checkpoint 8, inspect security state rather than relying on the dashboard icon alone. Confirm the expected input, the system response and the returned state. Preserve the evidence, reverse any ineffective adjustment and move to the next checkpoint only after the current result is clear.Validation note 8: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Checkpoint 9 — failed-node eligibility: reproduce the original symptom once and record the result at the expected update interval. Compare it with the last known-good behavior. Keep the change only when this specific checkpoint improves the failure without creating a new warning; otherwise restore the previous value.Validation note 9: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Verification checkpoint 10 focuses on fresh report. Observe the relevant state, event or log through two normal cycles and write down the timestamp. If the result is unchanged, undo the experimental change before testing another layer so the diagnosis remains controlled and reversible.Validation note 10: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    For checkpoint 11, inspect driver restart rather than relying on the dashboard icon alone. Confirm the expected input, the system response and the returned state. Preserve the evidence, reverse any ineffective adjustment and move to the next checkpoint only after the current result is clear.Validation note 11: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Determine whether the node is sleeping, unreachable or formally failed

    A battery node that is asleep is not automatically dead. Check whether the device is mains powered, listening, frequently listening or sleeping, then compare its last-seen time with its normal wake-up interval. A dead status after one missed exchange should lead to power and route checks, not immediate failed-node removal.

    For a battery device, replace or measure the battery and wake it using the manufacturer’s documented sequence while watching Z-Wave JS events. For a mains device, confirm line power and test a nearby repeater. Do not repeatedly ping a sleeping node; it will not respond until awake and the extra commands can fill its queue.

    Use route repair at the correct time

    Run an individual node heal only after power and physical placement are stable. Healing a powered-off device cannot succeed. Avoid treating a full-network heal as a universal fix, especially on large networks, because it creates substantial traffic and can obscure the original fault. Examine route statistics, failed transmissions and neighboring powered nodes first.

    The controller will permit failed-node removal only when the protocol considers the node failed. If exclusion is possible, prefer a normal exclusion so the device clears its network state. Use failed-node removal for a truly missing or broken node, then clean up entity references deliberately. Never remove a node merely because its entities show unavailable for a short period.

    Verify recovery beyond one successful ping

    • The node reports a fresh value or accepts a harmless command.
    • Interview and security state remain complete.
    • Transmission failures stop increasing during normal use.
    • Battery devices complete at least one expected wake cycle.
    • The node reconnects after a routine Z-Wave JS restart.

    If the node repeatedly becomes dead in the same location, investigate marginal power, metal enclosures, interference, missing repeaters or an unstable neighbor. Provide the node type, security level, firmware, route statistics, last-seen time and driver logs when escalating. That evidence is more useful than repeated network heals.

  • Home Assistant automation stopped triggering: step-by-step diagnosis

    Home Assistant automation stopped triggering: step-by-step diagnosis

    Short answer: Open the automation trace and confirm whether the trigger fired. If no trace exists, inspect the trigger and source entity. If a trace exists, follow it through conditions and actions instead of editing several steps at once.

    Preserve the failure

    Record when the automation last worked, the expected trigger time, the relevant entity states, and recent changes to Home Assistant, integrations, devices, helpers, or YAML. Do not delete and recreate the automation yet.

    1. Confirm it is enabled

    Check that the automation is enabled and that its mode is appropriate. Review the logbook for an unexpected disable event, reload, restart, or conflicting automation.

    2. Look for a trace

    A trace shows whether the trigger fired and where execution stopped. No trace usually points toward the trigger, source entity, or scheduling context. A trace ending at a condition means the automation worked as written but the condition evaluated false.

    3. Inspect the trigger

    Check entity IDs after device replacement or integration migration. For state triggers, distinguish a true state change from an attribute update. For numeric triggers, remember that crossing a threshold is different from already being beyond it. For time triggers, check the system timezone and helper value.

    4. Test conditions with real states

    Use the trace values from the failed run. Templates may receive unavailable, unknown, text, or null values. Confirm units and data types rather than assuming the displayed dashboard value is the raw state.

    5. Test actions safely

    Run only actions that are safe to test. Avoid unlocking doors, disabling alarms, opening valves, changing HVAC safety settings, or operating equipment without supervision. Verify target entities, service names, permissions, and integration availability.

    6. Check concurrency

    Single, restart, queued, and parallel modes behave differently when triggers overlap. A long delay or wait can make a single-mode automation appear unresponsive. The trace and system log should show dropped or cancelled runs.

    Make one change

    Duplicate or export the automation before a structural edit. Change one confirmed cause, reload if required, reproduce the trigger, and compare the new trace. If the failure began after an update, consult current release notes and official documentation before applying a workaround.

    Video walkthrough: trace an automation failure

    Michael Leen demonstrates how to follow Home Assistant automation traces and isolate the exact trigger, condition, or action that stopped a run. Use the video as a visual companion to the checks above; keep the written steps open so you can record each result and change only one variable at a time.

    Video: “Home Assistant Automation Not Working? Do THIS First!” by Michael Leen. Embedded from the creator’s original YouTube upload.

    Official sources

    Last reviewed: September 4, 2026.

    Find your next troubleshooting path

    Use the related guide that matches the next confirmed layer of the failure. Avoid changing unrelated systems at the same time.

    Detailed evidence checklist for Home Assistant automation stopped triggering

    Before another change, create a short incident record. Include the exact time the symptom appeared, what the system was doing, the last successful action, and every update or network change made during the previous day. Record the Home Assistant release, installation type, integration version, device model, firmware, connection method, current address, and relevant entity IDs. Screenshots are useful for visible states, but copy the exact error text because screenshots may crop the detail needed to search logs.

    Compare the failing item with one known-good item that uses the same path. If both fail, move outward toward shared services such as the integration, coordinator, add-on, DNS, router, cloud account, or Home Assistant host. If only one fails, stay close to that device: power, signal, address, credentials, firmware, permissions, and configuration. This comparison prevents a single-device problem from turning into an unnecessary system-wide rebuild.

    Network tests that prove the failing layer

    Use tests in layers. Confirm the address is current in the router or DHCP server. Confirm the Home Assistant host or container resolves the same name and reaches the intended address. Then test the actual documented service, port, or protocol. A dashboard loading on a phone proves only the phone’s path. A successful ping proves basic reachability, not authentication, WebSocket upgrades, multicast discovery, API encryption, event subscriptions, or application permissions.

    For segmented networks, document source VLAN, destination VLAN, direction, protocol, and port before editing a firewall rule. Test the smallest temporary exception and remove it if it did not help. Discovery traffic and control traffic may use different mechanisms. Seeing a device in discovery does not prove Home Assistant can maintain a working session.

    Configuration comparison procedure

    Export or photograph the current configuration without exposing secrets. Compare it with official documentation field by field: host, port, account, region, project, encryption setting, device identifier, and optional switches. Watch for trailing spaces, uppercase versus lowercase account names, obsolete hostnames, restored encryption keys, or an account belonging to the wrong home or region.

    Use Reconfigure or Reauthenticate before deleting an integration. Preserve entity IDs and note every automation, dashboard, script, scene, or helper that refers to them. If replacement becomes necessary, take a backup and map old entities to replacements. That makes rollback controlled rather than leaving broken references.

    Power, radio, and timing checks

    Do not interpret every unavailable state as software failure. Low-voltage devices may stay partly online while unstable power causes resets. Battery devices sleep and report on their own schedule. Wi-Fi and Bluetooth devices can associate yet fail at the application layer. Zigbee and Z-Wave devices depend on routes, radio conditions, and powered repeaters. Match the test to the technology instead of repeatedly pressing Reload.

    Allow enough time after each test. Cloud polling, sleepy devices, retained MQTT messages, mesh repair, Bluetooth advertisements, and DHCP changes do not update instantly. Define the expected interval, then wait through at least two normal cycles. If availability returns briefly, capture the next disconnect in logs instead of declaring success.

    Log-reading workflow

    Synchronize clocks and reproduce the problem once. Start with the first warning or error at that timestamp; later messages may be consequences. Group errors by layer: name resolution, timeout, refused connection, TLS certificate, unauthorized account, invalid token, missing permission, unsupported capability, malformed payload, device timeout, or rate limit. Each group suggests a different next action.

    Turn debug logging off after reproduction. Large files consume storage and bury the event. Redact tokens, passwords, keys, email addresses, public addresses, precise locations, and unnecessary unique identifiers. Keep the unredacted copy private for comparison with later tests.

    Safe change order

    1. Correct time, power, cabling, or an obviously stale address.
    2. Reload only the affected integration when documentation supports it.
    3. Use Reconfigure or Reauthenticate without deleting the entry.
    4. Restart only the affected device or add-on during a safe window.
    5. Restart Home Assistant when several components share the symptom or a change requires it.
    6. Update software after reading release notes and preserving rollback.
    7. Delete, exclude, reset, or rebuild only after safer checks prove it necessary.

    Post-repair validation

    Verify both directions. Confirm Home Assistant receives a fresh state, send one harmless command, and confirm the physical response. Check the returned state, logbook, history, and automation trace. Restart the affected component and verify automatic reconnection. During a maintenance window, confirm the repair survives a normal Home Assistant restart.

    Monitor long enough to cover the original pattern. If failure occurred overnight, after DHCP renewal, deep sleep, or token expiry, a five-minute test is insufficient. Record the confirmed cause and exact corrective change. Remove temporary firewall rules, extra logging, duplicate test integrations, and unused credentials.

    When to stop and escalate

    Stop if hardware overheats, power is unstable, storage reports errors, a controller backup fails, credentials are rejected across services, or firmware may be damaged. Escalate with versions, timestamps, topology, redacted logs, the first meaningful error, and results of each safe test. Do not repeat destructive steps while waiting for help.

    A strong report answers four questions: What still works? What exactly fails? What changed immediately beforehand? Which test most clearly separates the causes? Those answers help maintainers diagnose the correct layer.

    Verification checkpoint 1 focuses on trigger observation. Observe the relevant state, event or log through two normal cycles and write down the timestamp. If the result is unchanged, undo the experimental change before testing another layer so the diagnosis remains controlled and reversible.Validation note 1: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    For checkpoint 2, inspect trace creation rather than relying on the dashboard icon alone. Confirm the expected input, the system response and the returned state. Preserve the evidence, reverse any ineffective adjustment and move to the next checkpoint only after the current result is clear.Validation note 2: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Checkpoint 3 — condition result: reproduce the original symptom once and record the result at the expected update interval. Compare it with the last known-good behavior. Keep the change only when this specific checkpoint improves the failure without creating a new warning; otherwise restore the previous value.Validation note 3: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Verification checkpoint 4 focuses on choose branch. Observe the relevant state, event or log through two normal cycles and write down the timestamp. If the result is unchanged, undo the experimental change before testing another layer so the diagnosis remains controlled and reversible.Validation note 4: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    For checkpoint 5, inspect target entity rather than relying on the dashboard icon alone. Confirm the expected input, the system response and the returned state. Preserve the evidence, reverse any ineffective adjustment and move to the next checkpoint only after the current result is clear.Validation note 5: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Checkpoint 6 — automation mode: reproduce the original symptom once and record the result at the expected update interval. Compare it with the last known-good behavior. Keep the change only when this specific checkpoint improves the failure without creating a new warning; otherwise restore the previous value.Validation note 6: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Verification checkpoint 7 focuses on delay or wait. Observe the relevant state, event or log through two normal cycles and write down the timestamp. If the result is unchanged, undo the experimental change before testing another layer so the diagnosis remains controlled and reversible.Validation note 7: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    For checkpoint 8, inspect template variables rather than relying on the dashboard icon alone. Confirm the expected input, the system response and the returned state. Preserve the evidence, reverse any ineffective adjustment and move to the next checkpoint only after the current result is clear.Validation note 8: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Checkpoint 9 — YAML reload: reproduce the original symptom once and record the result at the expected update interval. Compare it with the last known-good behavior. Keep the change only when this specific checkpoint improves the failure without creating a new warning; otherwise restore the previous value.Validation note 9: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Verification checkpoint 10 focuses on service response. Observe the relevant state, event or log through two normal cycles and write down the timestamp. If the result is unchanged, undo the experimental change before testing another layer so the diagnosis remains controlled and reversible.Validation note 10: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    For checkpoint 11, inspect restart behavior rather than relying on the dashboard icon alone. Confirm the expected input, the system response and the returned state. Preserve the evidence, reverse any ineffective adjustment and move to the next checkpoint only after the current result is clear.Validation note 11: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

    Separate trigger failure from condition or action failure

    Open the automation trace before editing YAML. If no trace exists for the expected event, the trigger did not fire. If a trace exists and stops at a condition, the trigger worked and the condition evaluated false. If the trace reaches the action sequence, inspect the exact action result, target and service response. This distinction prevents rewriting a correct trigger when the real problem is downstream.

    In Developer Tools, observe the entity state or event that should start the automation. State triggers compare exact state strings and do not behave like numeric comparisons. Numeric-state triggers fire when a value crosses a threshold, not continuously while it remains beyond that threshold. Time, sun, template and event triggers each have their own restart and availability behavior.

    Check modes, waits and overlapping runs

    Review the automation mode. In single mode, a long delay or wait can block a new run. Restart mode cancels the previous run, queued mode preserves order, and parallel mode permits overlap. Choose the mode based on the device and intended behavior; changing it without understanding concurrency can create duplicate commands.

    Inspect wait templates, choose branches and templated targets using real trace variables. Confirm entity IDs still exist after device replacement or integration reload. A dashboard label may look unchanged while the underlying entity ID has changed. Reload automations after YAML edits and check the configuration before restarting Home Assistant.

    Verify the automation deterministically

    • Reproduce the actual trigger instead of pressing “Run actions” only.
    • Confirm the trace shows the expected trigger data.
    • Check every condition result and selected choose branch.
    • Verify the target entity receives the service call.
    • Repeat after a normal reload or restart.

    Running actions manually bypasses triggers and may bypass trigger-dependent variables, so it cannot prove the complete automation works. Use a safe test value or event, capture one trace and restore the original state afterward. If the automation fails only after restart, examine unavailable startup entities, template initialization and required delays rather than adding arbitrary repeated actions.

  • ESPHome device is offline in Home Assistant but still on Wi-Fi

    ESPHome device is offline in Home Assistant but still on Wi-Fi

    Direct answer: If an ESPHome device is still connected to Wi-Fi but appears offline in Home Assistant, the failure is usually between Home Assistant and the device’s native API—not necessarily the Wi-Fi connection itself. Confirm the device’s current IP address, test TCP reachability to the native API (normally port 6053), check the encryption key, and inspect live logs before reflashing or resetting anything.

    What “on Wi-Fi but offline” actually means

    A router may show a device in its client or DHCP list even when the device has stopped responding. The entry can also be stale. Home Assistant communicates with ESPHome through a persistent local native-API connection, so Wi-Fi association alone does not prove that the API is running or reachable.

    Before changing anything

    • Record the device name, current IP address, MAC address, board model, and power source.
    • Note the Home Assistant and ESPHome versions and when the problem began.
    • Save the current ESPHome YAML and encryption key securely.
    • Do not factory-reset, erase, or reflash the device yet.

    1. Confirm the device is truly online

    Refresh the router or access-point client list and compare the current IP with the address configured in Home Assistant. Look for frequent reconnects, a rapidly resetting uptime, weak signal, or a DHCP address that changed. A failing USB cable or undersized power supply can allow brief Wi-Fi connections while the application repeatedly restarts.

    2. Test the address Home Assistant is using

    Open Settings → Devices & services → ESPHome, select the affected device, and use Reconfigure if the saved hostname or IP address is wrong. The official integration supports changing the address without deleting and recreating the device.

    If a hostname such as device-name.local fails but the current IP works, the problem is probably mDNS or local name resolution. Correct the network or DHCP reservation instead of hard-coding a temporary address everywhere.

    3. Check the native API path

    ESPHome normally exposes its native API on TCP port 6053. Home Assistant and the device must be able to communicate locally on that path. Guest-network isolation, wireless client isolation, VLAN rules, firewall changes, or routing changes can leave internet access working while blocking Home Assistant.

    • Test from the same network segment as Home Assistant when possible.
    • Check only the specific path between Home Assistant and the device.
    • Do not disable the firewall broadly or expose the API to the public internet.

    4. Verify API configuration and encryption

    Confirm that the device YAML still contains the api: component. If API encryption is enabled, Home Assistant must have the matching 32-byte base64 Noise pre-shared key. A device can join Wi-Fi successfully while Home Assistant rejects the API connection because the stored key no longer matches.

    If the key changed, use the integration’s reconfiguration flow and enter the correct key. Do not post the key in forums, screenshots, or public logs.

    5. Read live logs before restarting

    In ESPHome Device Builder, select the device and open LOGS. The official Home Assistant integration also offers an option to subscribe to device logs. Look for:

    • successful Wi-Fi association and the assigned IP address;
    • native API startup or authentication errors;
    • watchdog resets, brownouts, boot loops, or repeated reconnects;
    • duplicate-name warnings or mDNS failures;
    • deep-sleep messages that explain expected offline periods.

    Redact Wi-Fi credentials, API keys, tokens, and public IP addresses before sharing logs.

    6. Check for duplicate device names

    Each ESPHome device must have a unique ESPHome name. Duplicate names can cause discovery and connection failures. This is different from the friendly name shown in the interface. If hardware was replaced using the same configuration, follow Home Assistant’s name-conflict repair flow instead of deleting both devices.

    7. Restart in the least-destructive order

    1. Reload or reconfigure only the affected ESPHome integration entry.
    2. If safe, power-cycle the low-voltage ESPHome device once.
    3. Restart network equipment only if several devices show the same network symptom.
    4. Compile or reflash only after validating the YAML and preserving a known-good backup.
    5. Use factory erase only as a final recovery step.

    How to verify the fix

    Confirm that Home Assistant reconnects, entity states update without delay, and live logs show a stable API client connection. Trigger one harmless command and verify both the physical response and the returned state. Watch the device for at least several minutes to make sure it is not reconnecting repeatedly.

    If it still fails

    Collect the board model, ESPHome and Home Assistant versions, current IP behavior, power details, relevant redacted logs, network layout, and the exact error from the integration. That evidence distinguishes an API authentication problem from name resolution, isolation, unstable power, firmware failure, or a deep-sleep configuration.

    Official references

    Last reviewed: September 5, 2026.

    Related Troubliq guides

    Find your next troubleshooting path

    Use the related guide that matches the next confirmed layer of the failure. Avoid changing unrelated systems at the same time.

    Confirm the exact failure boundary

    An ESPHome node can remain associated with Wi-Fi while Home Assistant cannot establish the native API connection. Verify the device’s current address, then compare basic reachability with the integration state and ESPHome logs. A successful ping or web-server response proves only part of the path; it does not prove that API authentication, encryption, name resolution, routing, and the configured port are correct.

    Determine whether one node or every ESPHome device is affected. A single failure points toward that device’s address, power, firmware, encryption key, or local route. Several devices failing together points toward Home Assistant networking, DNS, multicast discovery, VLAN policy, a firewall change, or the integration environment.

    Verify addressing and name resolution

    Compare the address Home Assistant is using with the current DHCP lease and the address printed in the device log. If it changed, correct the integration target or create a DHCP reservation. Avoid manually assigning an address inside the DHCP pool because a future collision can create an intermittent failure that looks like unstable firmware.

    If the integration uses a .local hostname, test resolution from the same network environment as Home Assistant. Multicast DNS can work from a phone on the main LAN while failing from a container, virtual machine, or isolated VLAN. That difference explains why the device looks online to one client but unavailable to Home Assistant.

    Check API credentials without exposing secrets

    Review the ESPHome configuration for the native API and encryption settings. Home Assistant and the device must use matching credentials. Restoring an older backup, copying a configuration, adopting a device from another dashboard, or reflashing older firmware can leave Wi-Fi working while the API rejects the connection.

    Never publish encryption keys, Wi-Fi passwords, fallback access-point credentials, or an unredacted secrets file. If a key must be rotated, update both sides deliberately and keep a known-good local configuration or supported physical recovery method in case an over-the-air update fails.

    Use logs before reflashing

    Match ESPHome log timestamps with Home Assistant’s connection errors. Look for repeated boots, API authentication failures, socket disconnects, watchdog resets, or network roaming. A device that connects to Wi-Fi briefly during a reboot loop may appear continuously present in an access-point list while never remaining available long enough for Home Assistant.

    Preserve the YAML and a known-good firmware image before changing configuration. Recompile or reflash only after the evidence points to firmware or API configuration. Reflashing before collecting logs can remove the clearest evidence and may make recovery harder.

    Verify the repair over time

    After reconnection, test sensor updates and commands through several normal reporting intervals. Restart only the device and confirm that Home Assistant reconnects automatically. During a maintenance window, confirm that it also reconnects after Home Assistant restarts. A few seconds of availability is not enough to prove stability.

    Record the confirmed cause, device address, firmware version, signal conditions, and the single change that resolved the problem. If the device later drops while remaining associated with Wi-Fi, return to power stability, access-point roaming, API logs, and local routing instead of deleting and recreating the integration immediately.

    Detailed evidence checklist for ESPHome device is offline in Home Assistant but still on Wi-Fi

    Before another change, create a short incident record. Include the exact time the symptom appeared, what the system was doing, the last successful action, and every update or network change made during the previous day. Record the Home Assistant release, installation type, integration version, device model, firmware, connection method, current address, and relevant entity IDs. Screenshots are useful for visible states, but copy the exact error text because screenshots may crop the detail needed to search logs.

    Compare the failing item with one known-good item that uses the same path. If both fail, move outward toward shared services such as the integration, coordinator, add-on, DNS, router, cloud account, or Home Assistant host. If only one fails, stay close to that device: power, signal, address, credentials, firmware, permissions, and configuration. This comparison prevents a single-device problem from turning into an unnecessary system-wide rebuild.

    Network tests that prove the failing layer

    Use tests in layers. Confirm the address is current in the router or DHCP server. Confirm the Home Assistant host or container resolves the same name and reaches the intended address. Then test the actual documented service, port, or protocol. A dashboard loading on a phone proves only the phone’s path. A successful ping proves basic reachability, not authentication, WebSocket upgrades, multicast discovery, API encryption, event subscriptions, or application permissions.

    For segmented networks, document source VLAN, destination VLAN, direction, protocol, and port before editing a firewall rule. Test the smallest temporary exception and remove it if it did not help. Discovery traffic and control traffic may use different mechanisms. Seeing a device in discovery does not prove Home Assistant can maintain a working session.

    Configuration comparison procedure

    Export or photograph the current configuration without exposing secrets. Compare it with official documentation field by field: host, port, account, region, project, encryption setting, device identifier, and optional switches. Watch for trailing spaces, uppercase versus lowercase account names, obsolete hostnames, restored encryption keys, or an account belonging to the wrong home or region.

    Use Reconfigure or Reauthenticate before deleting an integration. Preserve entity IDs and note every automation, dashboard, script, scene, or helper that refers to them. If replacement becomes necessary, take a backup and map old entities to replacements. That makes rollback controlled rather than leaving broken references.

    Power, radio, and timing checks

    Do not interpret every unavailable state as software failure. Low-voltage devices may stay partly online while unstable power causes resets. Battery devices sleep and report on their own schedule. Wi-Fi and Bluetooth devices can associate yet fail at the application layer. Zigbee and Z-Wave devices depend on routes, radio conditions, and powered repeaters. Match the test to the technology instead of repeatedly pressing Reload.

    Allow enough time after each test. Cloud polling, sleepy devices, retained MQTT messages, mesh repair, Bluetooth advertisements, and DHCP changes do not update instantly. Define the expected interval, then wait through at least two normal cycles. If availability returns briefly, capture the next disconnect in logs instead of declaring success.

    Log-reading workflow

    Synchronize clocks and reproduce the problem once. Start with the first warning or error at that timestamp; later messages may be consequences. Group errors by layer: name resolution, timeout, refused connection, TLS certificate, unauthorized account, invalid token, missing permission, unsupported capability, malformed payload, device timeout, or rate limit. Each group suggests a different next action.

    Turn debug logging off after reproduction. Large files consume storage and bury the event. Redact tokens, passwords, keys, email addresses, public addresses, precise locations, and unnecessary unique identifiers. Keep the unredacted copy private for comparison with later tests.

    Safe change order

    1. Correct time, power, cabling, or an obviously stale address.
    2. Reload only the affected integration when documentation supports it.
    3. Use Reconfigure or Reauthenticate without deleting the entry.
    4. Restart only the affected device or add-on during a safe window.
    5. Restart Home Assistant when several components share the symptom or a change requires it.
    6. Update software after reading release notes and preserving rollback.
    7. Delete, exclude, reset, or rebuild only after safer checks prove it necessary.

    Post-repair validation

    Verify both directions. Confirm Home Assistant receives a fresh state, send one harmless command, and confirm the physical response. Check the returned state, logbook, history, and automation trace. Restart the affected component and verify automatic reconnection. During a maintenance window, confirm the repair survives a normal Home Assistant restart.

    Monitor long enough to cover the original pattern. If failure occurred overnight, after DHCP renewal, deep sleep, or token expiry, a five-minute test is insufficient. Record the confirmed cause and exact corrective change. Remove temporary firewall rules, extra logging, duplicate test integrations, and unused credentials.

    When to stop and escalate

    Stop if hardware overheats, power is unstable, storage reports errors, a controller backup fails, credentials are rejected across services, or firmware may be damaged. Escalate with versions, timestamps, topology, redacted logs, the first meaningful error, and results of each safe test. Do not repeat destructive steps while waiting for help.

    A strong report answers four questions: What still works? What exactly fails? What changed immediately beforehand? Which test most clearly separates the causes? Those answers help maintainers diagnose the correct layer.