Blog

Direct answer: If Home Assistant 2026.9 does not show the Matter network map—or the map says the server is unsupported—do not reset or recommission your Matter devices. First confirm that Home Assistant Core is updated, the Matter integration is loaded, and the Matter Server is new enough to provide topology data. The map is a diagnostic view, not the control path itself: a missing map does not prove that your fabric, Thread credentials, or paired devices are broken.

What changed in Home Assistant 2026.9

Home Assistant 2026.9 brought the Matter Server’s network topology into the Home Assistant interface. The Matter panel can now show how devices connect: Wi-Fi versus Thread, routers and border routers, end devices, recognizable access-point or host names, and links whose appearance represents transport and reported signal information. Before this release, similar topology data could exist in the Matter Server’s own interface while remaining out of sight for most Home Assistant users.

The official release notes also state that when the Matter Server is too old to support the feature, the page should explain that instead of silently failing. That distinction matters. “Unsupported” is primarily a version or capability message. It is not evidence that the device must be recommissioned.

The network map closes an observability gap, but it does not change the fundamentals of Matter. Operational traffic still relies on local IPv6, permitted routing, discovery, a functioning Matter Server, and—when the device uses Thread—at least one usable Thread border router connected to the Home Assistant LAN.

Symptoms this guide covers

You may see no Show map button in the Matter panel, a message saying the Matter Server does not support the map, an empty or incomplete map, devices appearing without expected routes, Thread devices absent while Wi-Fi Matter devices appear, or a map that loads while one device remains unavailable. These symptoms belong to different layers and should not be treated as the same failure.

This guide does not assume that the map itself caused a device outage. If every Matter device became unavailable after an update, begin with service, network, IPv6, and border-router health. If the devices still respond and only the visualization is missing, preserve the working system and troubleshoot the map separately.

Failure matrix

No Show map control: confirm Home Assistant 2026.9 or later, the correct Matter panel, and that the frontend finished updating. Unsupported-server message: check the Matter Server version and update it through the supported installation path. Map loads but is empty: confirm devices are commissioned to this Matter fabric and allow topology data time to populate. Wi-Fi devices appear but Thread devices do not: inspect the Thread integration, border routers, preferred network, and local IPv6. One device is missing: check that device’s current availability and transport instead of rebuilding the entire fabric.

1. Confirm the version boundary

Record the Home Assistant Core version shown in Settings → System → Repairs or the system information page. The Matter network map is a Home Assistant 2026.9 feature. If the installation is older, the absence of the new control is expected. Update only through the supported process for your installation type, and make a current backup first.

If Core is already on 2026.9, install the latest available patch release rather than remaining on the initial .0 release. As of September 27, 2026, the official release page lists Home Assistant 2026.9.4. Patch releases contain bug fixes, so the exact patch level belongs in every useful problem report.

After an update, allow the frontend and integrations to load fully. Refresh the browser once. If another device or browser displays the new interface correctly, a stale client cache is more likely than a server-side Matter problem. Do not use cache clearing as the first explanation when server logs show an actual exception.

2. Separate Home Assistant Core from Matter Server

Home Assistant Core supplies the interface and integration, while the Matter Server handles Matter communication and topology data. Updating Core does not automatically prove that every supporting component is current in every installation type. Home Assistant OS and supervised installations typically manage the official Matter Server app through the normal app/update interface. Container and custom deployments require their own supported version management.

Open the Matter integration and inspect the available version and diagnostic information without exposing fabric credentials. If Home Assistant explicitly says the server is too old for the map, update the Matter Server through the supported channel. Avoid replacing it with an arbitrary development image merely to gain a feature.

After the Matter Server restarts, wait for the integration to reconnect. Verify an ordinary Matter command before evaluating the map. This establishes that the operational layer is healthy. If control fails after the server update, collect the Matter Server and Home Assistant logs before restarting additional components.

3. Confirm you are looking at the correct Matter fabric

A Matter device can participate in more than one ecosystem through multi-admin commissioning. The device shown in Apple Home, Google Home, or a manufacturer app is not automatically proof that it belongs to the Home Assistant Matter fabric. The Home Assistant map can only describe topology known to the connected Matter Server and its fabric.

Check the device list inside Home Assistant’s Matter integration. If the device does not exist there, the missing map node is expected. Do not remove it from another ecosystem blindly. Use the manufacturer’s and Home Assistant’s supported multi-admin flow if you intend to share the device with Home Assistant.

If the device exists and responds in Home Assistant but its map details are incomplete, allow time for data collection and compare again. Battery devices sleep to conserve power, and network information may not appear with the immediacy of a mains-powered router.

4. Distinguish Wi-Fi Matter from Matter over Thread

Matter is the application standard; Thread and Wi-Fi are network transports. A Wi-Fi Matter device communicates through the local IP network and access point. A Matter-over-Thread device depends on the Thread mesh plus a border router that forwards encrypted Matter traffic between Thread and the local IPv6 network.

Home Assistant’s 2026.9 map uses different link information to help distinguish these paths. If Wi-Fi Matter devices appear but Thread devices do not, concentrate on the Thread layer. If both transports are missing, first check the Matter Server, integration, and map capability rather than assuming every radio path failed simultaneously.

The official Matter documentation recommends keeping Matter devices, border routers, and Home Assistant on compatible local networks. Router or access-point options that claim to optimize multicast can interfere with discovery. A complex VLAN design can also violate the local-network assumptions Matter expects.

5. Check the Thread integration without changing credentials

Go to Settings → Connectivity → Thread. Confirm that the expected Thread networks and border routers appear. Home Assistant’s Thread documentation explains that the integration tracks Thread networks and credentials; it also notes that the preferred-network behavior is still not complete in every commissioning path because a mobile device’s preferred Thread network can influence onboarding.

Document which network Home Assistant marks as preferred, which network the phone uses, and which border routers are visible. Do not delete unknown credentials simply because multiple networks appear. Apple, Google, and Home Assistant border routers can create distinct Thread networks with different credentials.

If the OpenThread Border Router app is used, verify that it is running and inspect its logs. A serial or radio configuration problem can affect the Thread path even when the Matter Server itself is healthy. If the border router recently changed, preserve the prior configuration until the new path is verified.

6. Verify local IPv6

Thread is IPv6-only. Home Assistant’s Thread documentation specifically warns that a device can join the Thread mesh yet remain unreachable beyond it when IPv6 connectivity or forwarding is missing. Internet-provider IPv6 is not the same requirement; local IPv6 communication still matters even when the household has no globally routed IPv6 service.

Confirm that the Home Assistant host has local IPv6, that the router permits the required local path, and that container or VLAN layers do not discard IPv6 or multicast discovery. Avoid broad firewall exceptions. Make narrow, documented tests, and restore any rule that does not change the result.

If a device is controllable in Home Assistant, operational IPv6 for that path is already working at that moment. Do not redesign the network just because the visualization is incomplete. Use the map as supporting evidence, not as the only health test.

7. Interpret an incomplete map

An incomplete diagram can reflect sleeping devices, unavailable nodes, data that has not populated, a device on another fabric, or a server capability gap. It does not automatically identify weak signal. Compare the map with actual device availability, command success, event updates, and the Thread or Wi-Fi diagnostics available for that device.

Look for patterns. If all Thread end devices disappear but border routers remain, inspect the Thread mesh and credentials. If one battery sensor is absent while everything else works, wake or operate it using the manufacturer’s normal method and check again later. If the map itself never loads, focus on frontend, integration, and Matter Server logs.

8. Diagnose a map that loads while a device is unavailable

A topology line is not proof that application communication succeeds. The map may show the last known route while a device is currently asleep, powered off, blocked, or failing subscriptions. Open the device page and compare its entity update times, diagnostics, and command behavior.

For a Wi-Fi Matter device, confirm power, Wi-Fi association, local IPv6, VLAN rules, and mDNS behavior. For a Thread device, confirm border-router health, mesh coverage, and the network credentials used at commissioning. Avoid recommissioning until you have established that the current fabric relationship is actually lost.

Use Troubliq’s Matter device pairs but shows unavailable guide when device control is the problem rather than the map itself.

9. Safe restart order

Collect evidence first. Then reload the Matter integration if that control is available. If the server remains disconnected, restart only the Matter Server through its supported interface and wait for it to become ready. Restart Home Assistant once only when logs or integration state justify it. Rebooting the host, router, border routers, access points, and devices together destroys the evidence needed to identify the responsible layer.

After each change, verify one ordinary Matter command, one state update, and the map. Record what changed. If a server update fixes the map but not device availability, treat those as separate problems.

10. What to include in a useful problem report

Record Home Assistant Core version and patch, Matter Server version, installation type, whether the affected device uses Wi-Fi or Thread, device brand and model, border-router models, network layout, exact visible message, and the time of the last failure. Include sanitized logs from the Matter Server and Home Assistant.

Never publish setup codes, QR codes, fabric credentials, Thread credentials, authentication tokens, public addresses, or unredacted diagnostics. Troubliq’s Home Assistant Log Sanitizer can remove common private values locally in the browser before a log is shared.

Verification checklist

The Matter integration loads normally. An ordinary Matter command succeeds. State changes return to Home Assistant. The Matter Server meets the version required for the 2026.9 topology feature. The Show map control opens without an unsupported-server message. Expected Wi-Fi and Thread paths appear over time. Missing devices are investigated individually rather than erased from the fabric.

Rollback and recovery

If a supported Matter Server update introduces a new operational problem, preserve logs and use the recovery path documented for that installation type. Do not restore an entire Home Assistant backup solely because a visualization is absent. A full restore can roll back unrelated configuration and credentials.

If you changed a firewall or VLAN rule during diagnosis, restore the original rule when it did not help. If you restarted a border router, allow the mesh time to settle before drawing conclusions. If a device was accidentally removed, follow the manufacturer’s supported commissioning or multi-admin process; do not copy credentials from public examples.

Prevention

Keep Home Assistant Core and the official Matter Server on supported stable versions. Review release notes before monthly upgrades. Maintain a current backup. Record border-router ownership and Thread network names. Avoid unnecessary Thread channel changes and broad network changes. Keep Matter, Thread, and local IPv6 documentation with the household’s recovery notes.

Treat the map as a diagnostic aid. The best health check remains successful control, timely state updates, stable subscriptions, and predictable recovery after an ordinary restart.

Related Troubliq resources

Use the Smart-Home Diagnostic Decision Tree when the failing layer is unclear. Use the Device Unavailable Diagnostic for a protocol-neutral first pass. Check Home Assistant Problems Right Now for current version-specific notes.

Official sources and review record

Home Assistant 2026.9 release notes; Home Assistant Matter documentation; and Home Assistant Thread documentation.

Last reviewed: September 28, 2026. Testing disclosure: Troubliq synthesized current official documentation and documented platform behavior. We did not claim hands-on testing with every Matter device, Matter Server build, border router, router, VLAN, or Thread topology.

Direct answer: Do not delete the working integration first. Open the Home Assistant Core log immediately after reproducing the error and find the import exception that appears before “Invalid handler specified.” The popup is a wrapper: the actionable cause is usually an incompatible custom component, a missing Python dependency, a duplicate package, or a Core-version regression in the integration’s config flow.

This guide covers the frontend message “Config flow could not be loaded” with “Invalid handler specified” when adding, reconfiguring, or authenticating an integration. It is not a guide for ordinary invalid credentials or a device that is merely offline.

Symptoms and affected scope

• Adding an integration opens a popup containing Invalid handler specified.
• A previously working integration cannot reconfigure after a Core update.
• The log reports an import error, missing module, incompatible constant, duplicate package, or exception in config_flow.py.
• The official integration name matches a custom_components folder installed earlier.

These symptoms can look similar even though their causes sit in different layers. The safest approach is to preserve the current working state, identify the first failing layer, and change one variable at a time. This prevents a recoverable Config flow could not be loaded Invalid handler specified problem from turning into lost pairings, lost entities, or an inaccessible installation.

Ranked likely causes

• 1. A HACS or manually installed custom integration shadows the built-in integration domain.
• 2. The custom component is not compatible with the installed Home Assistant Core version.
• 3. A dependency failed to install or two incompatible copies of a Python package are loaded.
• 4. Home Assistant Core or the official integration has a confirmed regression.
• 5. Browser cache is stale, but only after server-side logs show no import failure.
• 6. The integration files are incomplete after a failed update or restore.

Before changing anything

Make a current backup, record versions and installation type, capture the exact first error, and remove secrets from any notes. Do not delete integrations, reset devices, erase databases, or reflash firmware as an opening move. If equipment is hot, swollen, wet, arcing, smoking, or connected to mains wiring that must be opened, stop and use qualified help.

Least-destructive diagnostic order

1. 1. Create a current backup before changing integration files. Do not remove the config entry, device registry records, or entities merely because the setup dialog failed. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
2. 2. Open Settings → System → Logs. Clear the view if needed, reproduce the error once, and return immediately to the log. Expand the first traceback associated with homeassistant.config_entries, homeassistant.loader, or the integration domain. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
3. 3. Record the exact integration domain and the first import or module error. The last line “Invalid handler specified” is less diagnostic than the earlier exception that prevented the config-flow handler from loading. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
4. 4. Check whether /config/custom_components contains a folder with that domain. A custom integration can shadow an official integration even when the UI label looks identical. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
5. 5. If a matching custom component exists, read its release notes and compatibility statement. Update it through its supported manager, or disable it reversibly by renaming the folder and restarting Home Assistant. Do not delete its files before a backup. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
6. 6. Restart Home Assistant once and retry the flow. If the built-in integration now loads, the shadowing custom component was the cause. Preserve its configuration until you decide whether migration is needed. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
7. 7. If no custom component matches, compare the installed Home Assistant Core version with the integration documentation and current upstream issues. A regression tied to one Core release should be handled with the official patch or a supported backup restore, not random package installation. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
8. 8. For dependency errors, do not use pip inside Home Assistant OS or a managed container. Managed installations rebuild dependencies and unsupported manual packages can make the environment less reproducible. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
9. 9. Check available Core updates and release notes. Install a stable patch only after a backup. If the error began immediately after an update and no fixed patch exists, restore the pre-update backup using the official recovery path. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
10. 10. Test in a private browser window only after server-side import errors are resolved. Browser cache cannot repair a Python import exception, but it can retain stale frontend flow state. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
11. 11. Reconfigure or reauthenticate through the integration’s flow instead of deleting it. Modern integrations may support a reconfigure flow that updates address or credentials without losing device/entity associations. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
12. 12. If the traceback identifies a genuine official-integration bug, collect sanitized diagnostics, Core version, installation type, and the minimal traceback. Remove tokens, API keys, hostnames, GPS data, and account identifiers before sharing an upstream report. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.

Choose the correct branch

• Matching custom_components domain: treat shadowing or incompatibility as the leading cause.
• Error began with a Core patch: inspect official release notes and upstream issue status before altering files.
• Missing third-party Python module: update or remove the component that declares it; do not modify managed Python manually.
• Only one browser fails and logs are clean: clear site data or test a private window after confirming the backend flow works.

How to interpret the results

If the evidence points to a HACS or manually installed custom integration shadows the built-in integration domain. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to the custom component is not compatible with the installed Home Assistant Core version. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to a dependency failed to install or two incompatible copies of a Python package are loaded. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to Home Assistant Core or the official integration has a confirmed regression. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to browser cache is stale, but only after server-side logs show no import failure. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to the integration files are incomplete after a failed update or restore. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

Verified repair and final checks

The integration dialog should open, complete without a server exception, and preserve or create the expected config entry. Confirm related entities load, no new import traceback appears after restart, and reauthentication or reconfiguration works without deleting the entry.

A repair is not verified merely because an error banner disappears. Confirm the underlying connection or service, observe fresh state data, and test after a controlled restart where appropriate. Keep the previous configuration until the new state has remained stable.

Rollback and recovery

Keep the backup and the original custom component folder until the fixed integration is verified. If a patch worsens the site, restore the supported prior backup. Do not restore only selected database tables unless official recovery instructions require it.

Write down each change before making it. Reversibility matters: a documented URL, service setting, serial path, integration state, or firmware version is much easier to restore than a configuration changed in several places at once.

Prevention

Review custom integrations before Core updates, avoid duplicate domains, keep HACS components current, retain pre-update backups, and test reconfiguration before an urgent credential change is needed.

Review this setup after platform, firmware, router, certificate, or host changes. Backups should exist off the device and should be periodically checked for visibility and required encryption material.

Privacy and safety

Never publish access tokens, API keys, encryption keys, Wi-Fi credentials, public IP addresses, precise locations, camera URLs, door-lock states, alarm details, or complete unsanitized diagnostics. Do not weaken TLS, firewall rules, authentication, or network isolation simply to make an error disappear.

Testing disclosure

This guide is based on the current official documentation and linked upstream reports. Troubliq did not physically test every device, adapter, network, phone, host, or installation variant described. Device-specific behavior can differ; preserve backups and follow the manufacturer’s safety instructions.

Sources

• Integration reconfigure flow guidance
• Test a connection in config flow
• 2026.7 Google config-flow regression
• 2026.2 LIFX config-flow regression
• Home Assistant common tasks and backups

Last reviewed: September 27, 2026.

Next: use the Home Assistant Error Decoder to match the exact message, or return to the current Home Assistant problems hub.

Detailed diagnostic reference

Read the traceback in order

The popup is produced after Home Assistant cannot obtain a valid config-flow handler. Find the first exception for the domain. Later wrapper messages repeat the consequence and can distract from the missing module, import name, dependency, or component error that caused it.

Check domain shadowing

Home Assistant resolves integrations by domain. A custom_components folder with the same domain can override the bundled integration. Record the folder and version, then disable it reversibly and restart once to test the official component.

Identify stale custom code

Search the traceback for removed constants, renamed helpers, or imports from old Home Assistant APIs. Those are compatibility failures in the custom component, not credential problems. Update the component or keep it disabled until its maintainer supports the installed Core release.

Avoid managed-environment package edits

Home Assistant OS and official containers manage Python dependencies. Installing packages manually with pip can create a temporary success that disappears on restart or conflicts with the next update. Repair the integration declaring the dependency.

Separate backend and frontend faults

If the log contains an import traceback, browser cache is not the cause. Use a private window only after the backend flow loads without errors. This prevents repeated cache clearing from hiding the actionable server evidence.

Protect an existing config entry

Do not delete a working or partially working entry before testing reconfigure or reauthenticate. Deletion can remove device/entity associations and automation references while leaving the broken flow code unchanged.

Handle a confirmed regression

Compare the exact Core version, installation type, and integration domain with the official issue. Prefer a fixed stable patch. If no fix exists and the failure is critical, restore the complete supported pre-update backup rather than mixing component files.

Sanitize diagnostic evidence

Share the integration domain, version, minimal traceback, and reproduction steps. Remove tokens, API keys, email addresses, hostnames, GPS coordinates, camera endpoints, and account identifiers. Do not upload a complete configuration archive publicly.

Verify after the repair

Open the flow, complete a harmless reconfiguration when possible, restart Home Assistant, and confirm the domain loads without import warnings. Check that entity identifiers and automations remain intact.

Completion criteria

The config flow opens reliably, the entry configures or reauthenticates, no related traceback returns after restart, and the fix does not depend on an unsupported manual package or deleted registry data.

Direct answer: First decide whether the app fails only at home, only away from home, or everywhere. A home-only failure points to the internal URL, Wi-Fi isolation, local-network permission, DNS, or router behavior. An away-only failure points to the external URL, remote-access service, firewall, DNS, or TLS certificate. Failure everywhere usually means the Home Assistant server is down, the saved URL is wrong, or authentication must be reset.

This guide covers the official Android and iOS Home Assistant Companion Apps. It assumes the Home Assistant web interface can be tested from at least one browser. It does not recommend exposing port 8123 directly to the internet.

Symptoms and affected scope

• The app displays “Unable to connect to Home Assistant.”
• The app works on mobile data but not home Wi-Fi, or works on Wi-Fi but not mobile data.
• A certificate, hostname, timeout, or connection-refused message appears.
• Notifications arrive but dashboards do not load.
• The browser works while the app fails, or the reverse.

These symptoms can look similar even though their causes sit in different layers. The safest approach is to preserve the current working state, identify the first failing layer, and change one variable at a time. This prevents a recoverable Home Assistant Companion App cannot connect problem from turning into lost pairings, lost entities, or an inaccessible installation.

Ranked likely causes

• 1. The saved internal or external URL is wrong, includes the wrong port, or points to an old hostname.
• 2. iOS local-network access is denied, Android network restrictions are active, or the phone is on a guest VLAN.
• 3. Hairpin NAT or split DNS is missing, so an external hostname cannot loop back from the home network.
• 4. The HTTPS certificate is expired, incomplete, self-signed, or issued for a different hostname.
• 5. A reverse proxy, firewall, VPN, Private DNS, content filter, or ad blocker interrupts the WebSocket connection.
• 6. The server is unavailable, restarting, or reachable only from another subnet.

Before changing anything

Make a current backup, record versions and installation type, capture the exact first error, and remove secrets from any notes. Do not delete integrations, reset devices, erase databases, or reflash firmware as an opening move. If equipment is hot, swollen, wet, arcing, smoking, or connected to mains wiring that must be opened, stop and use qualified help.

Least-destructive diagnostic order

1. 1. From a browser on the same phone and network, open the exact URL saved in the app. Record whether DNS fails, the connection times out, the certificate is rejected, or the login page appears. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
2. 2. Test the same URL once on Wi-Fi and once on mobile data. This two-path test is more useful than reinstalling the app because it identifies which side of the route is failing. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
3. 3. Open the app’s server connection settings and inspect the Home Assistant URL. Use a complete URL with https:// when TLS is configured. If external port 443 forwards to the Home Assistant service through a proxy, do not append :8123 to the public hostname. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
4. 4. On iOS, verify Settings → Apps → Home Assistant → Local Network is enabled. On Android, remove battery or data restrictions only when they are actually blocking the app; do not grant unrelated permissions. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
5. 5. If local access fails, confirm the phone is not on a guest network and that client isolation is disabled for the trusted home SSID. Test the Home Assistant host’s local address from another trusted device. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
6. 6. If the public hostname works outside but not inside, configure supported split DNS or router NAT loopback. Do not weaken TLS verification or replace the hostname with a private address while away from home. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
7. 7. Inspect the certificate in a browser. Confirm it is current, covers the exact hostname, and provides a complete chain. A browser exception is not an acceptable permanent fix for an app that sends authentication tokens. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
8. 8. If a reverse proxy is used, verify WebSocket forwarding and the Home Assistant trusted-proxy configuration. A normal login page can load while the persistent app connection still fails. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
9. 9. Disable VPN, Private DNS, filtering, or security apps temporarily one at a time for diagnosis. Restore each control after the test. Do not leave protective controls disabled. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
10. 10. Before resetting app data, back up notification-related settings and verify the Home Assistant user credentials. Reset the connection only after URL, network, and TLS tests identify the app state as the remaining cause. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.

Choose the correct branch

• Works on cellular only: focus on local-network permission, guest Wi-Fi, split DNS, and NAT loopback.
• Works on Wi-Fi only: focus on the external hostname, remote-access service, router forwarding, TLS, and carrier/VPN filtering.
• Browser works, app fails: compare the exact saved URL, app permissions, certificate trust, and stale authentication state.
• Neither browser nor app works: troubleshoot server availability and routing before changing the app.

How to interpret the results

If the evidence points to the saved internal or external URL is wrong, includes the wrong port, or points to an old hostname. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to iOS local-network access is denied, Android network restrictions are active, or the phone is on a guest VLAN. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to hairpin NAT or split DNS is missing, so an external hostname cannot loop back from the home network. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to the HTTPS certificate is expired, incomplete, self-signed, or issued for a different hostname. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to a reverse proxy, firewall, VPN, Private DNS, content filter, or ad blocker interrupts the WebSocket connection. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to the server is unavailable, restarting, or reachable only from another subnet. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

Verified repair and final checks

Verify dashboard loading, entity updates, a fresh app launch, one Wi-Fi-to-cellular transition, and a notification round trip. Confirm that the connection uses the intended HTTPS hostname and that no certificate warning was bypassed.

A repair is not verified merely because an error banner disappears. Confirm the underlying connection or service, observe fresh state data, and test after a controlled restart where appropriate. Keep the previous configuration until the new state has remained stable.

Rollback and recovery

If a URL edit makes the app worse, restore the recorded prior URL. If proxy changes fail, restore the last known configuration and restart only the proxy. Keep a browser session open during changes so you do not lock yourself out.

Write down each change before making it. Reversibility matters: a documented URL, service setting, serial path, integration state, or firmware version is much easier to restore than a configuration changed in several places at once.

Prevention

Use one documented external hostname, valid automated TLS renewal, supported remote access, stable internal DNS, and a trusted non-guest Wi-Fi network. Record the internal and external paths before changing routers.

Review this setup after platform, firmware, router, certificate, or host changes. Backups should exist off the device and should be periodically checked for visibility and required encryption material.

Privacy and safety

Never publish access tokens, API keys, encryption keys, Wi-Fi credentials, public IP addresses, precise locations, camera URLs, door-lock states, alarm details, or complete unsanitized diagnostics. Do not weaken TLS, firewall rules, authentication, or network isolation simply to make an error disappear.

Testing disclosure

This guide is based on the current official documentation and linked upstream reports. Troubliq did not physically test every device, adapter, network, phone, host, or installation variant described. Device-specific behavior can differ; preserve backups and follow the manufacturer’s safety instructions.

Sources

• Companion App networking
• Companion App errors
• Connection security level
• HTTP integration and reverse proxies

Last reviewed: September 24, 2026.

Next: use the Home Assistant Error Decoder to match the exact message, or return to the current Home Assistant problems hub.

Detailed diagnostic reference

Build a four-path test

Test the saved URL from the phone on home Wi-Fi, the same phone on cellular, another device on home Wi-Fi, and an external browser. This matrix separates app state from server state, and local routing from public routing, without reinstalling anything.

Interpret DNS failures

A hostname-not-found response means the device cannot resolve the name. Compare the phone’s DNS provider, VPN, Private DNS, router DNS, and split-DNS record. Do not replace a public HTTPS hostname with an insecure numeric address as a permanent workaround.

Interpret timeouts and refusals

A timeout usually indicates filtering, routing, or an unreachable host. Connection refused means the address answered but nothing accepted the requested port. These outcomes require different checks; neither is fixed by clearing the app cache.

Check WebSocket behavior

Home Assistant uses a persistent WebSocket after the initial page loads. A proxy may serve the login screen correctly while failing to upgrade the connection. Review the proxy’s WebSocket forwarding and timeout configuration using its official documentation.

Validate TLS completely

Confirm the certificate covers the exact hostname, is within its validity dates, and supplies the intermediate chain. Test renewal before expiration. Never install an unknown root certificate or turn off certificate validation merely to silence the app.

Handle split DNS safely

When the public hostname cannot loop back through the router, configure a local DNS record that returns the internal proxy address while preserving the same HTTPS hostname. This avoids maintaining different identities and keeps certificate verification meaningful.

Review phone permissions narrowly

Local Network permission on iOS is directly relevant. Location permission may affect SSID-based internal URL selection, but it should be granted only when that feature is used. Avoid granting contacts, microphone, or unrelated permissions to solve a network error.

Reset only the affected layer

If network and browser tests pass, remove and re-add only the saved server connection or reset the app according to official guidance. Record notification settings and device name first so duplicate mobile_app entities can be identified safely.

Remote-access safety

Prefer Home Assistant Cloud, a properly configured reverse proxy, or a secure VPN. Do not expose the default service directly without TLS and access controls. Rate limits and strong unique credentials protect the login but do not replace safe network design.

Completion criteria

The app should open from a cold start, update entities, switch between Wi-Fi and cellular, reconnect after screen lock, and receive a fresh notification. Verify that all paths use the intended hostname and no certificate exception remains.

Direct answer: An “Unsupported system” warning is not one single fault. It is Supervisor reporting that a specific host requirement—such as the operating system, OS-Agent, AppArmor, D-Bus, NetworkManager, systemd-resolved, CGroup v2, or the Home Assistant OS version—does not meet its supported baseline. Open Settings → System → Repairs, identify the exact unsupported check, and fix that check rather than suppressing the warning.

This guide applies to Home Assistant OS and supervised installations that expose Supervisor and the Repairs dashboard. It does not apply to Home Assistant Container or Core installations, which do not use Supervisor’s supported-host evaluation in the same way.

Symptoms and affected scope

• A Repairs notification says the installation or system is unsupported.
• Supervisor stops offering some updates or repeatedly logs an unsupported condition.
• The warning appeared after a host OS change, a kernel change, installing extra host software, or restoring an older image.
• The system still appears to work, which makes it tempting to ignore the warning.

These symptoms can look similar even though their causes sit in different layers. The safest approach is to preserve the current working state, identify the first failing layer, and change one variable at a time. This prevents a recoverable Home Assistant unsupported system problem from turning into lost pairings, lost entities, or an inaccessible installation.

Ranked likely causes

• 1. Home Assistant OS is more than four major releases behind.
• 2. A supervised installation is running on an unsupported operating system or an altered host.
• 3. OS-Agent is missing, stopped, outdated, or unreachable.
• 4. AppArmor, D-Bus, NetworkManager, systemd-resolved, or CGroup v2 is absent or misconfigured.
• 5. Unsupported extra software or conflicting containers are installed on the supervised host.

Before changing anything

Make a current backup, record versions and installation type, capture the exact first error, and remove secrets from any notes. Do not delete integrations, reset devices, erase databases, or reflash firmware as an opening move. If equipment is hot, swollen, wet, arcing, smoking, or connected to mains wiring that must be opened, stop and use qualified help.

Least-destructive diagnostic order

1. 1. Create a current full backup and download a copy away from the Home Assistant host. Confirm that the backup appears in the backup list and retain the encryption emergency kit if encryption is enabled. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
2. 2. Open Settings → System → Repairs and expand the unsupported item. Record the exact check name and the suggested more-info link. Do not treat the umbrella phrase “unsupported system” as the diagnosis. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
3. 3. Check Settings → System → Updates. If Home Assistant OS is old, update one offered OS release at a time and allow the host to finish rebooting. Do not remove power during an operating-system update. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
4. 4. For an OS-Agent warning, confirm the service exists and is running using the official OS-Agent instructions for the supervised host. Home Assistant OS already includes OS-Agent; an OS installation showing this warning should normally be rebooted and updated before deeper host changes. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
5. 5. For an AppArmor warning, verify the kernel boot parameters and AppArmor service rather than disabling the check. AppArmor is part of the supported security boundary. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
6. 6. For D-Bus, NetworkManager, systemd-resolved, or CGroup warnings, compare the host with the official supported supervised-installation requirements. Correct the named service only; do not replace several networking components at once. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
7. 7. If the warning names unsupported software, inventory containers and packages added outside Home Assistant. Stop only the conflicting component after documenting its configuration. Avoid deleting volumes or configuration while diagnosing. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
8. 8. If the operating system itself is unsupported, plan a backup-and-restore migration to Home Assistant OS or another officially supported installation type. A clean migration is safer than forcing Supervisor to accept an incompatible host. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.

Choose the correct branch

• Home Assistant OS: prioritize OS updates, a controlled reboot, storage health, and official recovery procedures.
• Supervised: verify the exact supported Debian release and every required host service before changing Supervisor.
• Container or Core: the message likely comes from a different component or an old supervised configuration; confirm the actual installation type before following supervised-host commands.

How to interpret the results

If the evidence points to Home Assistant OS is more than four major releases behind. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to a supervised installation is running on an unsupported operating system or an altered host. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to oS-Agent is missing, stopped, outdated, or unreachable. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to appArmor, D-Bus, NetworkManager, systemd-resolved, or CGroup v2 is absent or misconfigured. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to unsupported extra software or conflicting containers are installed on the supervised host. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

Verified repair and final checks

Return to Repairs after the repair and select recheck when offered. Confirm that the exact unsupported condition disappears, Supervisor can refresh update information, backups remain visible, add-ons start, and the host survives one controlled reboot. A working dashboard alone is not proof that the host is supported.

A repair is not verified merely because an error banner disappears. Confirm the underlying connection or service, observe fresh state data, and test after a controlled restart where appropriate. Keep the previous configuration until the new state has remained stable.

Rollback and recovery

If a service change breaks networking, use local console access and reverse only the last documented change. If migration fails, reinstall the prior supported image and restore the downloaded backup. Never test recovery by deleting the only working installation.

Write down each change before making it. Reversibility matters: a documented URL, service setting, serial path, integration state, or firmware version is much easier to restore than a configuration changed in several places at once.

Prevention

Keep Home Assistant OS and Supervisor current, avoid placing unrelated workloads on a supervised host, document host-level modifications, retain off-device backups, and review Repairs after every host or kernel update.

Review this setup after platform, firmware, router, certificate, or host changes. Backups should exist off the device and should be periodically checked for visibility and required encryption material.

Privacy and safety

Never publish access tokens, API keys, encryption keys, Wi-Fi credentials, public IP addresses, precise locations, camera URLs, door-lock states, alarm details, or complete unsanitized diagnostics. Do not weaken TLS, firewall rules, authentication, or network isolation simply to make an error disappear.

Testing disclosure

This guide is based on the current official documentation and linked upstream reports. Troubliq did not physically test every device, adapter, network, phone, host, or installation variant described. Device-specific behavior can differ; preserve backups and follow the manufacturer’s safety instructions.

Sources

• Home Assistant OS version
• Unsupported operating system
• OS-Agent issues
• Unsupported software
• AppArmor issues

Last reviewed: September 24, 2026.

Next: use the Home Assistant Error Decoder to match the exact message, or return to the current Home Assistant problems hub.

Detailed diagnostic reference

Read the exact Repairs identifier

Supervisor groups several host checks under an unsupported-system banner. Preserve the identifier shown in Repairs and the linked more-info page. An operating-system check, OS-Agent check, AppArmor check, D-Bus check, NetworkManager check, systemd-resolved check, and CGroup check require different remedies; treating them as one warning causes unnecessary host changes.

Separate unsupported from unhealthy

Unsupported describes a configuration outside the maintained baseline. Unhealthy can block Supervisor operations because a required service or condition is currently failing. Record both states independently. Clearing an unsupported notice does not prove the host is healthy, and a healthy-looking dashboard does not prove the installation is supported.

Check update visibility

An outdated Home Assistant OS can stop Supervisor from refreshing component update information. Compare the installed OS release with the releases offered in Settings. If updates are absent while the OS is far behind, use the official OS recovery path rather than installing random packages on the host.

Plan a supervised-host migration

Before migrating, inventory add-ons, storage mounts, USB devices, static addresses, certificates, and external databases. Download a full backup and its emergency kit. Install the supported target, restore the backup, then verify each hardware path and network dependency before decommissioning the old host.

Document host services

For supervised installations, record the status of OS-Agent, AppArmor, D-Bus, NetworkManager, systemd-resolved, Docker, and CGroup v2. Change only the service named by the repair. A broad package upgrade or networking replacement can create a second failure while hiding the first.

Avoid suppressing the symptom

Ignoring or hiding a Repairs notification does not restore support. Do not patch Supervisor files, disable evaluation code, or spoof the operating-system identity. Those changes make future updates less predictable and remove useful evidence from support requests.

Verify storage before upgrades

Low free space, filesystem errors, and failing media can make an ordinary update look like a Supervisor compatibility problem. Check storage health and available space before a major OS update. Keep the backup off the same storage device.

Prepare local recovery access

Host-level networking repairs can remove remote access. Confirm local console access, the device location, and a rollback path before changing NetworkManager, DNS, or firewall configuration. For remote installations, schedule an onsite fallback rather than gambling on an untested network restart.

Escalation package

A useful support package includes installation type, Core/Supervisor/OS versions, the exact Repairs identifier, relevant sanitized Supervisor lines, recent host changes, and the result of the official recheck. Exclude tokens, public addresses, serial numbers when unnecessary, and complete backups.

Completion criteria

The repair is complete only when the named Repairs item clears, Supervisor refreshes update data, add-ons and backups remain available, networking survives a controlled reboot, and no replacement unhealthy condition appears. Record the final versions and change that resolved it.

When the warning returns after a reboot

If the same repair returns after every restart, look for a persistent host configuration rather than repeatedly selecting recheck. Confirm that required services are enabled at boot, the correct kernel parameters remain active, the supported operating-system release is actually running, and no startup automation recreates a conflicting container or network configuration. Compare the first Supervisor evaluation after boot with the later state. A condition that appears only during startup may indicate service ordering; a condition that remains indicates the requirement is still unmet. Record boot logs before restarting again, because later logs may omit the first failure.

Direct answer: When Zigbee2MQTT and several Home Assistant add-ons go offline together, first determine whether the failure is DNS, MQTT, or the Zigbee adapter—do not reset the coordinator or re-pair devices. A message such as getaddrinfo ENOTFOUND, EAI_AGAIN, Name does not resolve, or Temporary failure in name resolution points toward DNS. ECONNREFUSED, an authentication failure, or a TLS error means the hostname resolved but the broker connection failed. Serial-port and adapter initialization errors belong to a different branch.

Symptoms this guide covers

This workflow is for Home Assistant installations where Zigbee2MQTT, Mosquitto, or another app stopped communicating after an update, restart, network change, or host-name change. Typical symptoms include all Zigbee entities becoming unavailable at once, Zigbee2MQTT restarting repeatedly, the Zigbee2MQTT frontend loading while MQTT never connects, several apps failing to resolve internal names, or logs naming a broker host that cannot be found.

It does not assume that Home Assistant 2026.9 has one universal DNS defect. The 2026.9 release is useful version context because settings and connectivity surfaces changed, but a temporal association is not proof of a Core regression. Match the exact log layer before changing anything. The same diagnostic order also applies to later releases unless their release notes identify a more specific breaking change.

Preserve evidence before restarting anything

• Download or confirm a recent Home Assistant backup before changing app configuration.
• Copy the first meaningful Zigbee2MQTT error after startup, not hundreds of repeated reconnect lines.
• Record the configured MQTT server value without copying its password.
• Note whether Mosquitto, Zigbee2MQTT, and other affected apps are running, stopped, or restarting.
• Record whether the failure began after a Core, Operating System, Supervisor, app, router, VLAN, or DNS change.

Remove usernames, passwords, access tokens, public IP addresses, device identifiers, Wi-Fi names, and coordinates before sharing logs. A broker URL may embed credentials, so redact it carefully.

Read the error by diagnostic layer

Step 1: decide whether the outage is broad or isolated

A broad simultaneous outage is the strongest clue. If every Zigbee entity becomes unavailable while Zigbee2MQTT reports an MQTT connection problem, the coordinator may still be operating normally. Zigbee2MQTT translates Zigbee events into MQTT messages; when the broker path breaks, Home Assistant stops receiving those messages and can make a healthy mesh look dead.

If only one device fails while Zigbee2MQTT remains connected to MQTT and other devices update normally, DNS is unlikely. Start with the individual device, its battery, nearby routers, interference, or last-seen history. If Zigbee2MQTT cannot initialize its adapter before it attempts MQTT, use the serial-port and coordinator diagnostic guide as the closer route.

Step 2: verify the MQTT server value

Zigbee2MQTT requires an MQTT server connection. Its official configuration documentation shows server values such as mqtt://localhost:1883 and notes that the Home Assistant Mosquitto app commonly uses the internal host core-mosquitto. The correct value depends on how Zigbee2MQTT is installed. A Home Assistant app, a separate Docker container, and a remote host do not share the same meaning of localhost.

• For the Home Assistant app arrangement, compare the value with the current app documentation and your broker configuration.
• For separate Docker containers, confirm both containers share the intended network and that the broker service name still exists.
• For a remote broker, confirm the hostname or fixed address still identifies the same machine.
• Check for spelling mistakes, an obsolete domain suffix, an accidental space, the wrong URI scheme, or an incorrect port.

Do not publish the complete configuration when asking for help. Zigbee2MQTT supports placing the server, username, password, and network key in a separate secrets file; preserve those boundaries.

Step 3: separate DNS from reachability

DNS answers the question “what address belongs to this name?” Reachability answers “can the client connect to that address and port?” These are different failures. A resolution error occurs before authentication. A connection-refused error normally means resolution succeeded and a host actively rejected the requested port. A timeout can indicate routing, firewall, a stopped service, or a host that never replied.

When an authorized diagnostic environment shows that the broker is reachable by numeric address but not by its configured name, that is useful evidence for DNS. Use the comparison only as a temporary test. Permanently hard-coding an internal app address may create a fragile setup because managed addresses can change. Restore the documented hostname-based configuration after correcting name resolution.

If multiple unrelated apps fail to resolve internal or external names at the same time, widen the investigation to the Home Assistant host, Supervisor/app network, upstream DNS server, router, VLAN rules, and recent network changes. If only Zigbee2MQTT fails and every other app resolves names normally, first scrutinize its exact server value and execution environment.

Step 4: verify Mosquitto without changing Zigbee

Confirm that the broker is installed, started, and not trapped in its own restart loop. Read its log at the same timestamp as the Zigbee2MQTT attempt. If Mosquitto records no incoming attempt while Zigbee2MQTT reports a DNS error, the connection likely never reached the broker. If Mosquitto records the attempt and rejects it, focus on credentials, permissions, client identity, or TLS instead of DNS.

Use a dedicated non-administrator MQTT account with only the access required by the deployment. Do not disable authentication as a diagnostic shortcut on a network you do not fully trust. If credentials recently changed, update the secret in one controlled step, restart only the affected client, and inspect the first new log sequence.

Step 5: interpret authentication and TLS errors correctly

An authentication error proves more than it appears to: the client reached something capable of speaking MQTT. Rechecking DNS repeatedly will not repair a rejected username or password. Verify the account, password source, ACL, and whether the broker expects anonymous or authenticated connections.

TLS errors also need their own branch. Confirm whether the configured URL begins with mqtt:// or mqtts://, whether the port matches that choice, whether Home Assistant’s clock is correct, whether the certificate covers the broker hostname, and whether the issuing CA is trusted. Do not bypass certificate verification permanently simply to silence an error; that can hide interception or a wrong destination.

Step 6: check the coordinator only after MQTT is healthy

Once Zigbee2MQTT reaches and authenticates to MQTT, any remaining startup error can be evaluated separately. Official Zigbee2MQTT troubleshooting notes that many startup crashes come from inability to communicate with the adapter. Look for USB discovery failures, an incorrect adapter type, a changed device path, another process holding the port, insufficient power, or a remote adapter that changed address.

Prefer stable device identifiers over transient names such as /dev/ttyUSB0 when the platform exposes them. For network coordinators, use a reserved address when the vendor recommends one and validate the correct TCP mode. Never flash firmware, erase coordinator storage, or create a new Zigbee network merely because the MQTT broker was unavailable.

Safe repair paths and what each result means

The hostname is wrong or obsolete

Correct only the MQTT server value, save, and restart Zigbee2MQTT once. A successful broker connection without adapter errors confirms the name was the blocking layer. If the new hostname resolves but authentication fails, the DNS problem is fixed and the next layer now needs attention.

The broker is stopped

Start or repair Mosquitto, then observe its log before restarting other services. If it stops again, investigate that failure rather than creating a restart loop. Storage exhaustion, invalid configuration, port conflicts, and permission problems require different repairs.

Only internal names fail

Review recent router, DNS, VLAN, Supervisor, and host changes. Restore the documented resolver path rather than scattering numeric addresses across configurations. After the correction, verify at least two affected names and then restart only the clients that did not reconnect automatically.

The broker rejects credentials

Update the dedicated client’s secret or broker account as appropriate. Do not paste passwords directly into logs or support posts. A clean successful CONNACK or a normal Zigbee2MQTT “connected to MQTT server” message is the expected validation result.

MQTT works but the adapter fails

Preserve the Zigbee network data, then check the configured adapter path and type, USB extension and power, device exclusivity, and firmware compatibility. This branch is independent of DNS; changing resolver settings further is unlikely to help.

Verification checklist

• Mosquitto remains running and its log shows the expected client connection.
• Zigbee2MQTT completes startup without DNS, authentication, TLS, or adapter errors.
• The Zigbee2MQTT frontend shows the existing network rather than an empty newly formed network.
• Home Assistant receives fresh state updates from multiple mains-powered and battery devices.
• A controlled command reaches one non-safety-critical test device and its resulting state returns.
• No unrelated app continues reporting the same resolution failure.

Do not validate using door locks, alarms, garage doors, heaters, medical equipment, or other safety-critical devices first. Choose a lamp or sensor where a delayed or duplicated command cannot create harm.

Rollback and recovery

If a single configuration change makes the condition worse, restore the previous value from your notes and restart only the affected service. If several settings were changed together, stop and restore the known-good app configuration or backup rather than guessing. A Home Assistant backup can restore configuration, but confirm its date and encryption key availability before depending on it.

If Zigbee2MQTT unexpectedly presents onboarding or no longer recognizes the network, stop before creating a new network. Verify that the correct data directory, configuration file, coordinator, and network key are mounted. Preserve the current directory before any reinstall. Re-pairing should be a last resort after confirming that the coordinator backup and network data cannot be recovered.

When to escalate

Escalate to the relevant project only after isolating the layer. For a Home Assistant host or Supervisor DNS failure affecting several apps, include installation type, Core/Operating System/Supervisor versions, sanitized resolver symptoms, the time the issue began, and whether a rollback changes it. For Zigbee2MQTT, include its version, installation method, sanitized first error, broker type, and coordinator model. For Mosquitto, include the broker-side rejection or startup error without credentials.

Open upstream issues are reports, not proof that every similar installation has the same defect. Search for your exact error and version, read maintainer responses, and avoid claiming a universal regression until it is confirmed or documented in release notes.

Prevention

• Keep a current encrypted backup and separately store the recovery key.
• Record the broker hostname, port, TLS mode, and installation topology without recording its password.
• Use stable hostnames and reserved addresses where the relevant documentation recommends them.
• Read breaking-change notes before major Home Assistant, Zigbee2MQTT, broker, or operating-system updates.
• Update one layer at a time when practical and verify MQTT plus several devices afterward.
• Retain a short sanitized baseline log showing a normal startup sequence.

Evidence and testing disclosure

Applies to: Home Assistant 2026.9-era installations using Zigbee2MQTT with Mosquitto or another MQTT broker; the layered method also applies to later versions. Expected result: the configured broker name resolves, Zigbee2MQTT authenticates, the adapter initializes, and existing devices resume state updates without rebuilding the network. Verification method: compare the first startup error with broker logs and validate one layer at a time. Testing status: this guide synthesizes documented behavior and diagnostic logic; Troubliq did not reproduce every installation topology or claim a universal 2026.9 regression. Last reviewed September 29, 2026.

• Official Home Assistant 2026.9 release notes
• Official Home Assistant 2026.9 changelog
• Official Zigbee2MQTT MQTT configuration
• Official Zigbee2MQTT startup troubleshooting

Related Troubliq diagnostics

Use the Home Assistant Error Decoder to classify a sanitized log message. If the broker connects but the coordinator does not, follow the serial-port and radio checklist. For current version-specific reports, check Home Assistant Problems Right Now. Remove all private data before sharing logs in the Troubliq community.

Direct answer: An ESPHome invalid-encryption-key error means the device and Home Assistant do not share the same 32-byte base64 native API key. Copy the key from the device’s current ESPHome YAML or Device Builder configuration into the Home Assistant integration’s reconfiguration flow. If the device was flashed with a different key, update Home Assistant to that key; do not disable API encryption as a shortcut.

This article concerns ESPHome native API encryption, not Wi-Fi passwords, OTA passwords, dashboard login credentials, or MQTT authentication. ESPHome 2026.1 removed deprecated API password authentication and requires API encryption for secure native API use.

Symptoms and affected scope

• The device is online and answers ping, but Home Assistant cannot connect.
• Logs mention an invalid encryption key, Noise handshake failure, or authentication failure.
• The problem began after adopting a device, restoring YAML, rotating secrets, or reflashing.
• ESPHome logs work from one installation but Home Assistant shows the device unavailable.

These symptoms can look similar even though their causes sit in different layers. The safest approach is to preserve the current working state, identify the first failing layer, and change one variable at a time. This prevents a recoverable ESPHome invalid encryption key problem from turning into lost pairings, lost entities, or an inaccessible installation.

Ranked likely causes

• 1. Home Assistant stores an old key while the device firmware contains a new one.
• 2. The YAML references the wrong secret, or two devices unintentionally share or swap secret names.
• 3. A copied key includes spaces, quotes, truncation, or invalid base64.
• 4. The device was adopted or recompiled from a different ESPHome installation.
• 5. YAML indentation or a merge placed the encryption key outside the api.encryption block.
• 6. The user is changing the OTA password or Wi-Fi key instead of the native API key.

Before changing anything

Make a current backup, record versions and installation type, capture the exact first error, and remove secrets from any notes. Do not delete integrations, reset devices, erase databases, or reflash firmware as an opening move. If equipment is hot, swollen, wet, arcing, smoking, or connected to mains wiring that must be opened, stop and use qualified help.

Least-destructive diagnostic order

1. 1. Confirm the device is powered, on the expected network, and reachable at its current address. An unreachable device cannot prove an encryption mismatch; solve power, Wi-Fi, DHCP, and VLAN routing first. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
2. 2. Open the device’s current ESPHome configuration. Locate api, then encryption, then key. If the key uses !secret, open the matching secrets file locally. Never paste the key into public logs, forums, screenshots, or diagnostic exports. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
3. 3. Verify the key belongs to this exact device. A valid ESPHome API key is a 32-byte value represented as base64; visual similarity is not enough when several devices use generated keys. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
4. 4. In Home Assistant, open Settings → Devices & services → ESPHome and choose Reconfigure for the affected entry when available. Enter the device’s current key and submit the flow. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
5. 5. If reconfigure is unavailable, record the device name, entities, automations, and current address before removing anything. Prefer reauthentication or reconfiguration over deleting the integration. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
6. 6. Validate the YAML structure. The encryption block must be nested under api. Check recent ESPHome validation output for warnings about misplaced keys or YAML merges. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
7. 7. If the source configuration is lost but OTA access still works from the ESPHome installation that built the device, restore the project or compile a controlled update with a new unique key. Keep the device powered and close to reliable Wi-Fi during the update. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
8. 8. If neither the source key nor OTA access exists, physical serial recovery may be required. Back up any available configuration first and follow the board-specific flashing procedure. Disconnect mains-powered hardware and use a qualified person where enclosure access exposes hazardous voltage. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
9. 9. After rotating a key, update Home Assistant immediately and store the new secret in the appropriate local secrets file. Do not reuse one key across every ESPHome device. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
10. 10. Restart only the ESPHome integration or device entry after the key is corrected. Rebooting all of Home Assistant is rarely needed and can hide the sequence that fixed the problem. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.

Choose the correct branch

• Online device with known YAML: update the Home Assistant config entry; no reflash is needed.
• Known key but wrong YAML nesting: correct YAML, validate, and flash only if the device firmware must change.
• Lost key with working OTA builder: generate a new unique key and perform a controlled OTA update.
• Lost key and no OTA access: use documented physical recovery; do not guess keys or disable network security.

How to interpret the results

If the evidence points to Home Assistant stores an old key while the device firmware contains a new one. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to the YAML references the wrong secret, or two devices unintentionally share or swap secret names. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to a copied key includes spaces, quotes, truncation, or invalid base64. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to the device was adopted or recompiled from a different ESPHome installation. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to YAML indentation or a merge placed the encryption key outside the api.encryption block. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to the user is changing the OTA password or Wi-Fi key instead of the native API key. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

Verified repair and final checks

Confirm the device entry becomes available, native API logs show a successful connection, entity states update, one harmless command round-trips, and the connection remains stable after a device restart. Verify the corrected key is stored only in private configuration.

A repair is not verified merely because an error banner disappears. Confirm the underlying connection or service, observe fresh state data, and test after a controlled restart where appropriate. Keep the previous configuration until the new state has remained stable.

Rollback and recovery

Before a firmware update, retain the last working YAML and binary when possible. If a new build fails to connect, restore the prior known-good build by the safest available method. Never interrupt power during flashing.

Write down each change before making it. Reversibility matters: a documented URL, service setting, serial path, integration state, or firmware version is much easier to restore than a configuration changed in several places at once.

Prevention

Generate a unique API encryption key for every device, store it in secrets.yaml, back up ESPHome projects securely, label adopted devices, and review validation warnings before flashing.

Review this setup after platform, firmware, router, certificate, or host changes. Backups should exist off the device and should be periodically checked for visibility and required encryption material.

Privacy and safety

Never publish access tokens, API keys, encryption keys, Wi-Fi credentials, public IP addresses, precise locations, camera URLs, door-lock states, alarm details, or complete unsanitized diagnostics. Do not weaken TLS, firewall rules, authentication, or network isolation simply to make an error disappear.

Testing disclosure

This guide is based on the current official documentation and linked upstream reports. Troubliq did not physically test every device, adapter, network, phone, host, or installation variant described. Device-specific behavior can differ; preserve backups and follow the manufacturer’s safety instructions.

2026.9 OTA error: “device did not offer encryption”

This OTA message is different from a Home Assistant native-API key mismatch. In ESPHome 2026.9, the esphome OTA platform can encrypt firmware transfers with the native API encryption key. Older firmware cannot offer that encrypted OTA handshake. If the new YAML requires ota: encryption: before the device has received a 2026.9-or-newer transition build, ESPHome correctly refuses to send the firmware image in plaintext.

Use this least-destructive migration order

1. Do not generate a replacement API key. If Home Assistant provisioned the existing key, copy that same value into api: encryption: key:. A new key can lock Home Assistant out of the device.
2. Keep the existing OTA password for the transition build. Build with ESPHome 2026.9.0 or newer, include the existing API encryption key, but do not require OTA encryption yet. The old firmware still expects its password.
3. Install once and inspect the device log. The expected transition result is Encryption: offered, plaintext accepted. This confirms that the running firmware can negotiate encrypted OTA.
4. Only then require encryption. Replace the OTA password with the encryption: block, install again, and confirm Encryption: required.

If the device has no native API, the official procedure uses a temporary API block with a unique generated key and reboot_timeout: 0s for the transition. If neither OTA route is available, serial flashing or the deliberately configured web-server OTA platform is the recovery path. Do not weaken firewall rules, reuse keys between devices, or paste keys into forums.

How to interpret the result

A refusal before the transition build normally means the running firmware cannot offer encrypted OTA; it does not prove that Wi-Fi, DNS, or the board is broken. A password error means the old firmware still expects the former OTA password. An API connection failure after installing a newly generated key points to a key mismatch between the device and Home Assistant. Roll back by restoring the previous YAML and original secret values; never publish the compiled firmware because it can contain Wi-Fi credentials and encryption material.

Evidence and testing disclosure: This branch follows the official ESPHome 2026.9 release notes, OTA documentation, native API documentation, and security guidance. Troubliq has not physically tested every board, bootloader, network, or historical configuration. Last reviewed October 1, 2026.

Sources

• ESPHome Native API component
• ESPHome security best practices
• ESPHome 2026.1 release notes
• ESPHome 2026.7 release notes

Last reviewed: September 24, 2026.

Next: use the Home Assistant Error Decoder to match the exact message, or return to the current Home Assistant problems hub.

Detailed diagnostic reference

Distinguish the four secrets

Wi-Fi credentials join the network, the native API encryption key protects Home Assistant communication, the OTA credential protects firmware updates, and an MQTT password authenticates a broker. Changing one does not repair another; identify which subsystem produced the log message.

Validate base64 without exposing it

The API key represents 32 bytes in base64. Use ESPHome validation locally rather than pasting the secret into an online decoder. Quotation marks, whitespace, a truncated copy, or the wrong secret reference can make a visually plausible key invalid.

Trace secret resolution

When YAML uses !secret, confirm which secrets.yaml file the active Device Builder instance reads. A restored project or second ESPHome installation may resolve the same secret name to a different value. Record the builder that last compiled the device.

Check YAML hierarchy

The encryption block belongs beneath api. Mis-indentation can move it outside the component or cause a merge to replace the intended block. Treat validation warnings as build failures until the resulting configuration is understood.

Use reconfiguration before deletion

Home Assistant can often update the key through the ESPHome entry’s reconfigure flow. Deleting the entry may break entity identifiers and automations while leaving the actual key mismatch untouched. Preserve the registry relationship whenever possible.

Rotate deliberately

If the key may have leaked, generate a new unique key, update the device through the trusted builder, then update Home Assistant. Perform the steps in a controlled window so the old key is not lost before the new firmware is reachable.

Recover an adopted device

Identify the original YAML, substitutions, packages, board type, and pin assignments before compiling. A generic replacement file can connect while silently changing relays, sensors, restore modes, or safety interlocks.

Protect mains-powered devices

Do not open an energized relay, plug, light controller, or appliance to reach serial pins. Disconnect power and follow the manufacturer’s isolation procedure. If hazardous voltage may be exposed, use a qualified technician.

Check after reconnection

Inspect API logs for successful encrypted handshake, confirm entity availability and timestamps, test one harmless command, and restart the device once. A single online state immediately after flashing is not enough to prove stable recovery.

Completion criteria

The correct device connects using its unique key, no Noise or authentication warning returns, secrets remain private, OTA access is documented, and the saved project can reproduce the running firmware without hidden credentials.

Direct answer: Stop Zigbee2MQTT, confirm no other service is using the coordinator, and verify the serial path and Ember adapter configuration before power-cycling or flashing anything. ASH_NCP_FATAL_ERROR and HOST_FATAL_ERROR mean communication between zigbee-herdsman and a Silicon Labs Ember coordinator failed; they do not automatically mean the Zigbee network database is lost.

This guide targets Silicon Labs EmberZNet coordinators used by Zigbee2MQTT, including USB and network-connected adapters. It does not apply to Texas Instruments zStack or deCONZ adapters, and it is separate from an individual device interview failure.

Symptoms and affected scope

• Zigbee2MQTT fails during startup with ASH_NCP_FATAL_ERROR or HOST_FATAL_ERROR.
• Logs show exceeded ACK timeouts, CRC errors, ASH disconnected, adapter reset, or inability to open the serial port.
• The error began after a reboot, USB renumbering, firmware update, migration, or enabling another Zigbee integration.
• A network coordinator works intermittently and disconnects under load.

These symptoms can look similar even though their causes sit in different layers. The safest approach is to preserve the current working state, identify the first failing layer, and change one variable at a time. This prevents a recoverable Zigbee2MQTT ASH_NCP_FATAL_ERROR problem from turning into lost pairings, lost entities, or an inaccessible installation.

Ranked likely causes

• 1. The configured serial path changed or points to a transient /dev/ttyUSB number.
• 2. ZHA, another Zigbee2MQTT instance, firmware tools, or host software already owns the adapter.
• 3. The adapter type or flow-control setting is wrong for the coordinator.
• 4. USB power, cabling, interference, pass-through, or virtualization is unstable.
• 5. Coordinator firmware is incompatible, corrupted, or not recommended for the adapter.
• 6. A TCP coordinator has packet loss, an unstable address, wrong port, or competing client.

Before changing anything

Make a current backup, record versions and installation type, capture the exact first error, and remove secrets from any notes. Do not delete integrations, reset devices, erase databases, or reflash firmware as an opening move. If equipment is hot, swollen, wet, arcing, smoking, or connected to mains wiring that must be opened, stop and use qualified help.

Least-destructive diagnostic order

1. 1. Preserve the Zigbee2MQTT data directory, configuration.yaml, coordinator backup, and network key before changing firmware or creating a new network. Do not press a coordinator reset button. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
2. 2. Stop Zigbee2MQTT cleanly. Also stop ZHA or any second Zigbee service that may open the same coordinator. One coordinator must have one active owner. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
3. 3. Check the configured serial port. Prefer a stable /dev/serial/by-id path for local USB hardware rather than /dev/ttyUSB0 or /dev/ttyACM0, which can change after reboot. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
4. 4. Confirm the configured adapter family matches the hardware. For current Silicon Labs coordinators, follow Zigbee2MQTT’s EmberZNet adapter guidance. Do not copy an adapter value from a guide for different silicon. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
5. 5. Review flow-control settings for the exact model. For hardware that expects software flow control, enabling RTS/CTS can produce startup failures. Use the manufacturer and Zigbee2MQTT documentation rather than guessing. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
6. 6. Inspect the host log for USB disconnects, resets, or pass-through errors. On a virtual machine, confirm the coordinator is attached to the guest after every host reboot. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
7. 7. Move a USB coordinator away from USB 3 ports, SSDs, and Wi-Fi radios using a quality shielded extension cable. Replace a suspect cable or underpowered hub before reflashing firmware. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
8. 8. For a network coordinator, reserve its address, test packet loss, verify the documented TCP port, and ensure only one client connects. Do not expose an unencrypted coordinator socket to untrusted networks. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
9. 9. Perform one controlled power cycle: stop the service, remove coordinator power for a short interval, reconnect it, confirm the stable path, then start Zigbee2MQTT. Repeated rapid cycling can obscure a power or ownership fault. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
10. 10. Compare coordinator firmware with the adapter vendor’s recommended Ember firmware and Zigbee2MQTT’s compatibility guidance. Flash only after backups exist and simpler causes are excluded. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
11. 11. Start Zigbee2MQTT and read the first complete startup sequence. Record the first error, not only the final fatal line; the first serial, permission, firmware, or socket error usually identifies the layer. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
12. 12. If the error persists on known-good power, cabling, configuration, and firmware, test the coordinator on a supported host without forming a new network. Hardware failure becomes more likely only after those controls pass. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.

Choose the correct branch

• Local USB: prioritize stable device path, exclusive ownership, permissions, extension cable, power, and VM pass-through.
• Ethernet/PoE coordinator: prioritize address reservation, TCP port, latency, packet loss, firmware, and single-client ownership.
• Error after migration: restore the original Zigbee2MQTT data directory and coordinator settings; do not create a fresh network unless recovery has failed and you accept re-pairing.
• CRC or ACK errors under load: investigate cable quality, USB interference, power, flow control, and firmware before blaming end devices.

How to interpret the results

If the evidence points to the configured serial path changed or points to a transient /dev/ttyUSB number. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to ZHA, another Zigbee2MQTT instance, firmware tools, or host software already owns the adapter. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to the adapter type or flow-control setting is wrong for the coordinator. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to USB power, cabling, interference, pass-through, or virtualization is unstable. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to coordinator firmware is incompatible, corrupted, or not recommended for the adapter. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to a TCP coordinator has packet loss, an unstable address, wrong port, or competing client. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

Verified repair and final checks

A successful recovery produces a clean adapter startup, loads the existing network, preserves the PAN and devices, allows one harmless device read or command, and remains connected through a Zigbee2MQTT restart. Verify several routers and sleepy devices over time.

A repair is not verified merely because an error banner disappears. Confirm the underlying connection or service, observe fresh state data, and test after a controlled restart where appropriate. Keep the previous configuration until the new state has remained stable.

Rollback and recovery

If a configuration change fails, restore the recorded serial block. If firmware flashing fails, use the adapter vendor’s recovery method and the backed-up coordinator/network data. Never erase the data directory as an initial fix.

Write down each change before making it. Reversibility matters: a documented URL, service setting, serial path, integration state, or firmware version is much easier to restore than a configuration changed in several places at once.

Prevention

Use stable serial paths, one coordinator owner, off-device backups, documented firmware versions, reliable power, USB extension cables, reserved network addresses, and change logs for coordinator updates.

Review this setup after platform, firmware, router, certificate, or host changes. Backups should exist off the device and should be periodically checked for visibility and required encryption material.

Privacy and safety

Never publish access tokens, API keys, encryption keys, Wi-Fi credentials, public IP addresses, precise locations, camera URLs, door-lock states, alarm details, or complete unsanitized diagnostics. Do not weaken TLS, firewall rules, authentication, or network isolation simply to make an error disappear.

Testing disclosure

This guide is based on the current official documentation and linked upstream reports. Troubliq did not physically test every device, adapter, network, phone, host, or installation variant described. Device-specific behavior can differ; preserve backups and follow the manufacturer’s safety instructions.

Sources

• Zigbee2MQTT startup failures
• EmberZNet adapters
• Adapter settings
• Supported adapters
• Upstream ASH fatal-error report

Last reviewed: September 24, 2026.

Next: use the Home Assistant Error Decoder to match the exact message, or return to the current Home Assistant problems hub.

Detailed diagnostic reference

Preserve coordinator identity

The Zigbee network depends on its PAN identifiers, network key, coordinator state, and Zigbee2MQTT database. Back up the entire data directory and coordinator backup before firmware work. A newly starting coordinator is not useful if it forms a different network.

Find the first error

HOST_FATAL_ERROR is often the terminal message after a more specific serial, CRC, ACK, permission, or socket failure. Read the startup log from the first adapter line and troubleshoot the earliest failure, not the last summary.

Prove exclusive ownership

Stop ZHA, other Zigbee2MQTT instances, firmware flashers, serial monitors, and host discovery services that may open the adapter. Restart only one owner. Simultaneous access can mimic firmware or hardware failure.

Use stable device paths

Map a USB coordinator through /dev/serial/by-id where supported. In virtual machines and containers, confirm that the stable host device is passed through, not only a transient tty number. Recheck the mapping after host reboots.

Measure the physical layer

Inspect host logs for disconnects and resets, test a short known-good extension cable, remove an unpowered hub, and separate the coordinator from USB 3 storage and radios. Change one physical variable at a time.

Respect model-specific flow control

RTS/CTS requirements differ by coordinator and firmware. A copied serial configuration can open the port yet fail the ASH exchange. Confirm adapter type, baud rate, and flow control against the exact vendor model.

Diagnose network coordinators

Reserve the coordinator address, verify the TCP scheme and port, measure packet loss, and prevent multiple clients. For PoE units, inspect switch power events. Keep the coordinator interface on a trusted network.

Treat firmware as a controlled change

Record the current firmware build and hardware revision. Use only vendor- or project-recommended firmware for that adapter. Do not flash merely because a fatal error appears once; eliminate ownership, path, power, and transport causes first.

Verify the old network

After recovery, confirm the coordinator reports the expected network, devices remain listed, routers respond, and battery devices check in naturally. Do not start mass re-pairing until network identity and backup restoration are confirmed.

Completion criteria

Zigbee2MQTT completes startup without ASH errors, retains the existing devices and network identifiers, survives a service restart, and stays stable during normal traffic. Preserve the final configuration and firmware record.