Category: General Troubleshooting

A Zigbee device that appears in ZHA, reaches most of the interview, and then fails is not the same problem as a device that never enters pairing mode. The radio has usually heard the device; the failure happens while Home Assistant requests endpoints, clusters, or basic attributes. That distinction prevents unnecessary coordinator resets.

What this failure pattern tells you

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

• The device is discovered but remains partially configured or marked unavailable.
• The interview repeatedly stalls near completion.
• A battery device pairs only when held beside the coordinator.
• The same device worked before a battery change, migration, or factory reset.

Most likely causes

• The sleepy device stopped responding before the interview finished.
• The device still remembers an earlier Zigbee network.
• Weak signal or 2.4 GHz interference interrupted cluster discovery.
• The coordinator or router is busy after a restart.
• A manufacturer-specific quirk needs a fresh interview or newer device support.

Before changing anything

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

Step-by-step diagnosis and repair

1. Create a Home Assistant backup before changing the Zigbee network.
2. Replace or fully charge the device battery; low voltage can allow pairing but fail sustained communication.
3. Factory-reset the device using its manufacturer procedure, then keep it awake throughout the interview by tapping its pairing button every few seconds.
4. Pair within a few feet of a powered Zigbee router or the coordinator, but keep USB coordinators away from USB 3 cables, hubs, Wi-Fi access points, and metal enclosures.
5. In ZHA, remove only the failed device entry—not the coordinator—then start Add Device and retry once.
6. If it still fails, restart Home Assistant once, wait for the Zigbee network to settle, and review Settings → System → Logs for ZHA, zigpy, endpoint, timeout, or unsupported-cluster messages.
7. Test another known-good device. If only one model fails, treat it as device-specific rather than rebuilding the network.

How to verify the repair

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

Common mistakes to avoid

• Do not delete the ZHA integration or erase the coordinator as a first step.
• Do not repeatedly power-cycle the coordinator during an interview.
• Do not assume a high percentage means the device is almost healthy; one missing endpoint can prevent usable configuration.

A practical decision rule

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

When to restore a backup

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

Frequently asked questions

Should I re-pair every Zigbee device?

No. A single interview failure rarely justifies rebuilding a working mesh.

Can Wi-Fi cause this?

Yes. Zigbee and 2.4 GHz Wi-Fi share spectrum, and proximity to access points or USB 3 equipment can make an intermittent failure look like a software bug.

When should I check device support?

After a clean reset, strong-signal pairing, and a second controlled attempt still fail for the same model.

Bottom line

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

Deep diagnostic worksheet

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

1. Record the device manufacturer, model, mains-or-battery status, pairing distance, and the exact stage where the interview stops. These details distinguish a sleepy end-device problem from a coordinator-wide problem.
2. Open the device page and note which entities, endpoints, and diagnostic values were created. A partially created device proves that discovery occurred even if cluster interrogation did not finish.
3. Compare the failure with a known-good Zigbee device paired from the same location. If the second device also struggles, investigate radio placement, interference, and coordinator health before blaming one product.
4. For battery devices, keep the unit awake throughout pairing according to its manual. Many devices sleep quickly after joining, which can interrupt the exchange of endpoint and attribute information.
5. Check the Home Assistant log at the exact pairing time. Preserve the manufacturer, model, IEEE address suffix, exception name, and retry sequence while removing credentials before sharing a report.
6. Inspect whether the device was previously joined to another coordinator. A proper factory reset is model-specific; merely removing a battery often does not erase the former network.
7. Move a USB coordinator away from USB 3 equipment and metal using a quality extension cable. Change only placement first; channel changes can require wider planning and should not be casual experiments.
8. After a failed attempt, remove only the incomplete device, restart nothing unless logs indicate a stuck integration, and allow the mesh to settle before one controlled retry.

Failure-pattern examples

• Fails only with one battery sensor: replace the battery, perform the documented factory reset, pair close to a stable router or coordinator, and keep the sensor awake. Do not rebuild ZHA.
• Several new devices fail from every room: test radio placement, host load, coordinator connectivity, and interference. Preserve the network database and investigate shared infrastructure.
• Device joins and controls work but some entities are missing: allow time for initialization, check disabled entities, confirm model support, and collect signatures before considering a device handler issue.
• Pairing works beside the coordinator but not at installation location: the join succeeded; the mesh path is the likely weakness. Add or reposition appropriate powered routers rather than repeatedly pairing.
• Failure began after a host migration: confirm the correct serial device path, coordinator type, extension cable, and restored Zigbee data before changing device firmware.

Advanced notes that prevent false fixes

• Treat a high interview percentage as a progress indicator, not proof that the remaining step is unimportant.
• Avoid channel changes unless interference evidence supports them and you understand how every device will be affected.
• A custom quirk should be considered only after obtaining the complete device signature and checking existing support.
• Battery voltage reported by a device can lag; a fresh known-good battery is a stronger test than one stale percentage reading.
• Powered Zigbee routers must be compatible and placed where they provide a useful route, not clustered beside the coordinator.
• When reporting a bug, include reproducible steps, ZHA diagnostics, logs, coordinator model and firmware, Home Assistant version, and device signature.

Final verification checklist

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

• Device remains available after the normal sleep interval.
• All expected endpoints and entities appear or unsupported ones are documented.
• A control or sensor update succeeds from the final installation location.
• The log contains no repeating interview retries.
• The test survives one normal Home Assistant restart.
• No unrelated Zigbee devices became unstable.

Official reference

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

Related Troubliq guides

• ZHA device interview recovery
• duplicate ESPHome device cleanup
• MQTT availability troubleshooting

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.

Quick answer: If Home Assistant Core becomes unresponsive and the Supervisor watchdog restarts it several minutes later, collect one complete failure cycle before changing anything. Check memory, CPU, disk I/O, database activity, blocked integrations, recorder growth, and the first error preceding the watchdog action. A watchdog restart is the recovery event, not necessarily the root cause.

Public reports describe Core 2026.9 systems becoming unresponsive without an obvious out-of-memory event. Because many unrelated failures produce the same visible symptom, this guide uses a measurement-first process and avoids claiming a universal fix.

Preserve evidence before restarting

• Note the exact time the interface stopped responding.
• Save Core, Supervisor, host, and add-on logs covering several minutes before the event.
• Record Core, OS, Supervisor, and database versions.
• Record CPU, memory, disk utilization, free space, and database size.
• List integrations or add-ons changed immediately before the first incident.

Confirm what is actually unresponsive

Test the local IP address from a second device. If the interface fails but SSH, the observer, or host metrics remain available, the host may be healthy while Core is blocked. If the entire machine disappears from the network, investigate power, storage, hardware, virtualization, and host networking instead.

Build a simple timeline

1. Last successful automation or state update
2. First delayed or failed request
3. First warning or exception in the log
4. Time the watchdog detected failure
5. Time restart began
6. Time Core became available again

The first abnormal event is more useful than the final watchdog message.

Check memory without assuming an OOM

Look for steadily increasing memory, sudden spikes, swap pressure, and the host kernel’s out-of-memory messages. If memory remains normal, do not label the incident a memory leak. A blocked event loop, slow storage, database lock, integration timeout, or network filesystem can make Core appear dead without exhausting memory.

Check the Recorder database

A large or unhealthy database can create long writes, migrations, purges, and startup delays. Record the database engine and size. Look for locked, malformed, disk-full, and unusually slow query messages. Do not delete the database as a diagnostic shortcut.

Reduce unnecessary high-frequency entities only after identifying them. Broad exclusions can remove history you need and may hide the actual source.

Check integrations and add-ons

Look immediately before the freeze for an integration generating repeated exceptions, reconnect loops, or blocking calls. If one component is consistently named, investigate its current release notes and issue tracker. Disable only the suspected nonessential component with a backup and a reversible plan.

Add-ons are separate processes but can still saturate storage, CPU, memory, or network resources. Compare their resource graphs with the incident time.

Check storage and host health

• Confirm adequate free disk space.
• Check for filesystem or I/O errors.
• On SD-card installations, treat repeated I/O errors as a possible storage failure.
• On virtual machines, inspect host contention and storage latency.
• Confirm system time and network connectivity remain stable.

Controlled isolation

1. Back up the current system.
2. Choose the strongest single suspect from the logs.
3. Change only that component.
4. Observe long enough to cover the normal failure interval.
5. If the freeze returns, restore the previous state and test the next evidence-backed suspect.

Changing several integrations, database settings, and network components together makes the result impossible to interpret.

Rollback or update forward?

If incidents began only after 2026.9 and no environmental change occurred, check later patch notes and the active issue report. Update forward when a patch explicitly addresses the condition. Roll back only with a verified pre-update backup and an understanding that database and configuration state will also move backward.

Do not do these things first

• Do not schedule automatic restarts to hide the problem.
• Do not disable the watchdog.
• Do not delete the Recorder database without diagnostic evidence.
• Do not remove every custom integration at once.
• Do not publish raw diagnostics containing secrets or personal data.

Decision tree

1. Did the whole host disappear? Investigate hardware, storage, power, virtualization, and host networking.
2. Only Core stopped responding? Inspect the first Core error and resource timeline.
3. Memory climbed continuously? Identify the component correlated with the growth.
4. Storage latency or database errors appeared? Protect the backup and diagnose storage or Recorder.
5. One integration loops before every freeze? Isolate that integration reversibly.
6. No local cause is visible and failure began with 2026.9? Compare the active issue and newer patch releases.

Incident reference

See Home Assistant Core issue #181318 for a current report of Core becoming unresponsive followed by a Supervisor watchdog restart. The report is a useful signal, but it does not establish one cause for every installation.

Last reviewed: September 23, 2026.

Additional evidence-based diagnostics

Measure event-loop symptoms

A blocked event loop can stop API and frontend responses while the host still answers. Look for warnings about blocking calls, integrations taking excessive setup time, executor saturation and long event-loop delays before the watchdog restart. Do not assume high CPU is required for Core to become unresponsive.

Correlate resource history

Compare CPU, resident memory, swap, disk latency, database writes and network errors across the minutes before the freeze. A value that rises after Core is already stuck may be a consequence. Prefer repeated correlations across two incidents before changing configuration.

Check Recorder workload

Recorder purges, repacks, migrations and high-frequency entities can create intensive storage activity. Record the database engine, size, purge schedule and relevant errors. Do not delete the database or broadly exclude entities until logs and timing make Recorder a credible suspect.

Inspect network-mounted dependencies

Integrations or backups that depend on an unavailable network share, DNS server or remote database can stall or retry. Compare network and resolver events with the freeze. Restore connectivity or disable only the proven nonessential dependency using a reversible change.

Review custom integration behavior

Repeated exceptions, rapid reconnect loops and synchronous calls from one custom integration can degrade Core. Confirm the component version and upstream compatibility. Disable only the strongest suspect after a backup, then observe for at least the normal interval between failures.

Separate add-on load from Core faults

Add-ons run separately but share host CPU, memory, disk and networking. A camera processor, database, backup job or log flood can starve Core. Compare add-on resource graphs and schedules with the timeline instead of removing add-ons indiscriminately.

Use the watchdog correctly

The watchdog restores availability when Core stops responding; it does not diagnose the cause. Keep it enabled. Automatic scheduled restarts can erase evidence and create the appearance of stability while the underlying lockup remains.

Build a controlled comparison

Change one variable, document it, and observe through the expected failure window. If the incident returns, reverse that change before testing the next hypothesis. Several simultaneous changes cannot produce reliable evidence and complicate rollback.

Validate durable recovery

Confirm Core remains responsive past the prior failure interval, entity timestamps remain current, automations execute, database writes continue, resource levels stabilize and one controlled Core restart completes without a new freeze.

Escalation package

Provide the complete version set, installation type, database engine, sanitized log window beginning before the freeze, resource timeline, watchdog time and changes already tested. Remove tokens, addresses, coordinates, camera URLs and personal entity names.

Testing disclosure

Troubliq has not reproduced every watchdog restart scenario. The article uses the cited upstream incident as a demand signal while keeping the diagnostic branches applicable to other measured causes; it does not assert that Home Assistant 2026.9 universally causes freezes.

Related Troubliq resources

Use the Home Assistant Error Decoder to match the exact message, then review the current Home Assistant problems hub for related verified guides.

Advanced interpretation and recovery

CPU interpretation

Sustained CPU saturation before each freeze suggests a workload or loop, but a brief spike during restart is expected. Break usage down by Core, add-ons and host services. If one integration floods logs or state updates at the same time, isolate it rather than increasing hardware blindly.

Memory interpretation

Track resident memory and swap over hours, not only the value after restart. A monotonic increase associated with one integration supports a leak hypothesis. Stable memory during a freeze shifts attention toward blocking I/O, event-loop stalls, database locks or network waits.

Disk-latency interpretation

High I/O wait, filesystem errors or long database commits can make Core unresponsive without high CPU. Check the storage device and host logs. On flash media, repeated read/write errors justify immediate backup and storage replacement planning.

Database-engine branch

SQLite problems are diagnosed through Core logs, database integrity and host storage. External MariaDB or PostgreSQL adds network, server, connection-pool and authentication layers. Confirm which engine is active before applying repair commands. Preserve statistics and backups before database work.

Automation-load branch

A looping automation can generate rapid service calls and state changes. Inspect traces and logbook activity near the incident. Disable only the confirmed automation and verify whether the event rate and responsiveness normalize; do not disable all automations as a long-term workaround.

Template and sensor branch

Templates that update excessively or reference many entities can create work across the state machine. Compare recently changed templates and high-frequency sensors with the timeline. Optimize only measured hot paths so useful state history is not lost.

Network timeout branch

Cloud integrations, DNS failures and unreachable local devices can generate reconnect loops. Well-behaved integrations should not block Core, but custom components may. Correlate the first timeout and component logger with the freeze before disabling anything.

Backup-job branch

Backup creation, compression, upload and retention can stress storage and CPU. If incidents align with scheduled backups, test the job separately, inspect destination availability and reduce overlap with database maintenance. Never stop a backup by cutting host power.

Thermal and power branch

Throttling, undervoltage and unstable power can cause broad slowness or host resets. Check platform health indicators and hardware logs. Replace suspect power supplies or cooling using manufacturer guidance; software changes cannot repair failing hardware.

Virtual-machine branch

Inspect host contention, ballooning, storage latency, snapshots and CPU scheduling. A responsive hypervisor with a stalled guest suggests a guest resource or device problem; simultaneous issues across guests point to the host.

Expected-result interpretation

If disabling one proven custom component prevents recurrence past the normal interval, investigate that component upstream. If database repair removes I/O errors and writes remain stable, monitor Recorder. If the whole host still stalls, leave Core configuration intact and escalate to hardware or virtualization diagnostics.

Recovery documentation

Record the last incident time, root-cause evidence, exact change, observation period and final versions. Preserve the pre-repair backup until the system operates normally through several expected cycles.

Prevention

Keep storage healthy, control high-frequency entities, review custom components before Core upgrades, stagger intensive backup and database tasks, monitor free space and resources, and retain logs long enough to capture the minutes before a watchdog event.

Log-rate diagnosis

A component writing thousands of repetitive messages can consume CPU, storage and I/O while hiding the first useful exception. Measure the logger and message that dominates the interval. Correct the component or temporarily raise only that logger’s threshold after preserving evidence. Do not disable all logging, because the next freeze would become harder to diagnose.

State-change diagnosis

Review the busiest entities and whether their update rate changed before the problem. A noisy power sensor, malformed MQTT publisher or template feedback loop can create excessive state and database activity. Correct the measured source, then confirm state-change and Recorder write rates return to normal without losing necessary monitoring.

Health-check interpretation

If the Supervisor watchdog restarts Core, record how long the health check failed and whether API, frontend and automation processing stopped together. A proxy-only outage should not normally require a Core restart. Matching the watchdog time to Core logs helps distinguish a real Core stall from an external access problem.

Post-fix observation window

Observe the installation beyond the longest previous interval between incidents. Include at least one scheduled backup, Recorder purge or other recurring workload that previously overlapped a freeze. A short period of responsiveness immediately after restart is not enough to establish a durable repair.

Safe temporary mitigation

If a nonessential integration is strongly implicated but no fix exists, keeping only that integration disabled can be a reasonable temporary mitigation. Document the lost functions, monitor the upstream issue and retest after a supported update. Do not normalize scheduled whole-system restarts as the permanent solution.

Direct answer: On Android, reliable zone tracking requires the Home Assistant Companion app to have location permission set to Allow all the time, the appropriate location sensors and Zone Based Tracking enabled, and a working connection to the Home Assistant server while away from Wi-Fi. Begin with the app’s Location History troubleshooting screen: it shows whether Android produced an update, why the app accepted or skipped it, and whether the update reached the server.

This guide addresses Home Assistant Android location or zone tracking that is not updating. It is designed to preserve working configuration and evidence before any reset, deletion, or re-pairing. Work in order and stop when the first confirmed cause is corrected. Screens and menu labels can vary by Home Assistant release and installation method.

Symptoms and scope

Use the following signs to decide whether this guide matches your problem. Similar-looking failures can come from different layers, so record what still works as carefully as what fails.

• The person or device_tracker entity remains home after the phone leaves.
• Zone enter or exit automations arrive late or not at all.
• Location updates work only while the app is open.
• Tracking works on home Wi-Fi but stops on cellular data.
• The app records a location but the entity in Home Assistant does not change.

Most likely causes, ranked

Start with the causes that fit the evidence. Do not apply every fix at once: simultaneous changes make it impossible to know what solved the problem and can create a second failure.

• 1. Android location permission is set to While using the app, approximate only, or otherwise restricted.
• 2. Zone Based Tracking or required location sensors are disabled in Companion App settings.
• 3. Battery optimization, sleeping apps, background-data limits, Data Saver, or manufacturer power management suspends the app.
• 4. The external Home Assistant URL, certificate, VPN, DNS, or mobile network cannot reach the server away from home.
• 5. Google Play services, device location, Wi-Fi/Bluetooth scanning, or GPS accuracy is impaired.
• 6. The app deliberately rejects stale, inaccurate, or duplicate readings; the location history explains the reason.

Safe diagnostic procedure

Before beginning, make a current backup when the procedure could affect configuration or stored data. Record the Home Assistant version, installation type, device or app version, the first failure time, and the last known working change. Redact secrets from every screenshot and log excerpt.

Step 1: Capture the exact failure

Open the Home Assistant Companion app → Settings → Companion app → Troubleshooting → Location tracking and enable Location History. Reproduce one departure or movement. Read the event details rather than guessing: determine whether Android generated an update, whether the app skipped it, and whether server delivery succeeded.

Interpretation: if this step changes the symptom, repeat the same controlled test once before moving on. If nothing changes, restore any temporary setting and continue. Keep a short note of the time, action, and result; that record prevents circular troubleshooting.

Step 2: Protect the current state

In Android Settings → Apps → Home Assistant → Permissions, set Location to Allow all the time and enable precise location where available. Menu names differ by manufacturer. Also confirm the phone’s main Location switch is on. Do not grant permissions to unrelated apps.

Interpretation: if this step changes the symptom, repeat the same controlled test once before moving on. If nothing changes, restore any temporary setting and continue. Keep a short note of the time, action, and result; that record prevents circular troubleshooting.

Step 3: Verify the affected layer

In Companion App settings, enable Location Zone and Zone Based Tracking as documented for Android. Review the device’s enabled sensors in Home Assistant. Avoid enabling every high-frequency sensor merely for troubleshooting; start with the minimum location features required for presence.

Interpretation: if this step changes the symptom, repeat the same controlled test once before moving on. If nothing changes, restore any temporary setting and continue. Keep a short note of the time, action, and result; that record prevents circular troubleshooting.

Step 4: Test the least-destructive cause

Remove Home Assistant from battery optimization or sleeping-app lists using the device maker’s supported settings. Allow background activity and unrestricted battery use when necessary. Samsung, Xiaomi, OnePlus, and other vendors add controls beyond stock Android, so verify after system updates.

Interpretation: if this step changes the symptom, repeat the same controlled test once before moving on. If nothing changes, restore any temporary setting and continue. Keep a short note of the time, action, and result; that record prevents circular troubleshooting.

Step 5: Inspect configuration and identity

Allow background data and cellular data for Home Assistant. If Data Saver is active, grant the app unrestricted data as appropriate. Turn off Wi-Fi and open the configured external Home Assistant URL in the app; a server connection failure is not a GPS failure.

Interpretation: if this step changes the symptom, repeat the same controlled test once before moving on. If nothing changes, restore any temporary setting and continue. Keep a short note of the time, action, and result; that record prevents circular troubleshooting.

Step 6: Check network, power, or permissions

Check the Companion app connection settings, internal URL, external URL, SSID rules, VPN, and certificate trust. Do not weaken TLS validation or expose Home Assistant directly merely to make tracking work. Repair the certificate, proxy, tunnel, or secure remote-access path.

Interpretation: if this step changes the symptom, repeat the same controlled test once before moving on. If nothing changes, restore any temporary setting and continue. Keep a short note of the time, action, and result; that record prevents circular troubleshooting.

Step 7: Apply the narrow repair

Review zone geometry and the Home zone radius. Overlapping zones, a huge Home radius, GPS drift, and short trips can make a correct location appear wrong. Compare the raw coordinates privately and never publish home coordinates or a screenshot showing your address.

Interpretation: if this step changes the symptom, repeat the same controlled test once before moving on. If nothing changes, restore any temporary setting and continue. Keep a short note of the time, action, and result; that record prevents circular troubleshooting.

Step 8: Observe through a full cycle

Send a one-time request-location notification only as a diagnostic if the device supports it. It can prompt an update, but it is not a substitute for background permission and may fail when the operating system cannot obtain a timely fix. Avoid frequent forced requests that drain the battery.

Interpretation: if this step changes the symptom, repeat the same controlled test once before moving on. If nothing changes, restore any temporary setting and continue. Keep a short note of the time, action, and result; that record prevents circular troubleshooting.

Installation and environment branches

Home Assistant OS or appliance-style installs

No events in Location History: focus on Android permission, sensors, battery management, and device location services.

Container, network, or account variation

Events exist but show skipped readings: inspect accuracy, age, duplicate suppression, and the reason recorded by the app.

Partial failure versus complete failure

Events are sent but server rejects or never receives them: focus on authentication, external connectivity, certificates, and server logs.

Multi-device or multi-hop environments

Entity changes but person does not: inspect the Person configuration and every tracker attached to that person; another tracker may still report home.

What not to do

• Do not delete the integration, device, database, app registration, or proxy configuration merely because it is the fastest visible button. Deletion can remove evidence and create new entity identities.
• Do not paste passwords, tokens, encryption keys, exact home coordinates, public URLs with credentials, or unredacted logs into a forum or support ticket.
• Do not disable firewalls, TLS verification, authentication, or other security controls as a permanent workaround. A useful test must be narrow, timed, and reversed.
• Do not make several network, software, and device changes together. Change one variable, observe the result, and keep the working rollback path.
• Do not assume a restart is a diagnosis. A restart can temporarily hide timing, memory, radio, storage, or connectivity faults without correcting them.

Verification checklist

Perform a controlled test that protects privacy: note the time, leave the Home zone by a safe margin, wait for a normal update, and check Location History. Confirm the device_tracker changes first, then the Person entity and finally the automation trace. Repeat on cellular data with the app closed and screen off. Return home and verify the reverse transition. One manual refresh while the app is open does not prove background tracking is fixed.

• The original symptom is gone under the same conditions that previously reproduced it.
• The relevant log has no new matching error after a normal update or restart cycle.
• Related entities, history, automations, or remote access still work.
• The repair survives one controlled restart of the affected component.
• Temporary troubleshooting exceptions have been removed or documented.

Rollback and recovery

Before clearing app data or deleting the mobile_app integration, record the device name, notification service name, enabled sensors, Person assignment, automations, widgets, and server connection settings. Re-registration can create new entity IDs and break notifications. Try permission, connectivity, and battery fixes first. If re-registration is necessary, repair each dependency deliberately and remove duplicates only after verification.

If the evidence points to failing hardware, a vendor outage, an upstream regression, or corrupted data that matters, stop improvising. Preserve the backup and diagnostic record, then escalate with the exact version, timestamp, error, minimal reproduction, and steps already tested. That produces a safer and faster answer than repeated resets.

Prevention

• Recheck background permissions after Android and vendor updates.
• Keep a secure external connection tested on cellular data.
• Use realistic non-overlapping zone radii.
• Review Location History when delays begin.
• Avoid aggressive battery-saving profiles for the Companion app.
• Document which tracker drives each Person entity.

Schedule a brief review after the next Home Assistant update or device firmware change. Confirm that the repaired path still works, remove obsolete workarounds, and update your private documentation. Prevention is most effective when it records why a setting exists, not just its value.

Diagnostic worksheet

For Home Assistant Android location or zone tracking that is not updating, write down five facts before asking for help: the exact error, the first failure time, the last working time, the smallest action that reproduces it, and the layer that still works. Add the Home Assistant Core version, installation type, relevant device or app firmware, network path, and whether the issue survives a restart. This worksheet separates a repeatable defect from a transient outage.

If you observe: The person or device_tracker entity remains home after the phone leaves

Confirm when this began and whether it affects one entity, one device, one integration, or the whole installation. Compare the result on the same network and, when relevant, through the alternate path. Then use the matching diagnostic step above. Do not jump to recovery until the observation is repeatable or the logs identify the failing layer.

If you observe: Zone enter or exit automations arrive late or not at all

Confirm when this began and whether it affects one entity, one device, one integration, or the whole installation. Compare the result on the same network and, when relevant, through the alternate path. Then use the matching diagnostic step above. Do not jump to recovery until the observation is repeatable or the logs identify the failing layer.

If you observe: Location updates work only while the app is open

Confirm when this began and whether it affects one entity, one device, one integration, or the whole installation. Compare the result on the same network and, when relevant, through the alternate path. Then use the matching diagnostic step above. Do not jump to recovery until the observation is repeatable or the logs identify the failing layer.

If you observe: Tracking works on home Wi-Fi but stops on cellular data

Confirm when this began and whether it affects one entity, one device, one integration, or the whole installation. Compare the result on the same network and, when relevant, through the alternate path. Then use the matching diagnostic step above. Do not jump to recovery until the observation is repeatable or the logs identify the failing layer.

If you observe: The app records a location but the entity in Home Assistant does not change

Confirm when this began and whether it affects one entity, one device, one integration, or the whole installation. Compare the result on the same network and, when relevant, through the alternate path. Then use the matching diagnostic step above. Do not jump to recovery until the observation is repeatable or the logs identify the failing layer.

Frequently asked questions

Should I delete and add everything again?

Usually not. Re-adding can change entity IDs, erase evidence, and hide the original cause. Use it only after backup, documentation, and the narrower checks in this guide.

Can I ignore the error if it starts working again?

A single brief interruption may be harmless, but a recurring error deserves timestamps and logs. Repetition after the same event often reveals a network, storage, power, permission, or token lifecycle problem.

Is updating Home Assistant always the fix?

No. Updates can contain fixes, but they also change dependencies and behavior. Read release notes, back up first, and match the error to a known fix before treating an update as diagnosis.

How much log information should I share?

Share the smallest relevant window around the failure, with secrets and personal data removed. Include versions and the exact action that caused the event. Avoid uploading complete logs publicly.

When should I escalate?

Escalate when safety, important data, repeated corruption, an upstream regression, or an account-side failure is involved, or when the least-destructive checks produce a clear error you cannot resolve.

Sources and review notes

Photo: Henry Perks on Unsplash. Last reviewed: September 22, 2026. Official documentation is the authority for supported configuration. Community and issue reports are useful for identifying recurring symptoms but do not prove that every installation has the same cause.

• https://companion.home-assistant.io/docs/core/location/
• https://companion.home-assistant.io/docs/troubleshooting/faqs/
• https://companion.home-assistant.io/docs/getting_started/connection-security-level/

Continue with the Device Unavailable Diagnostic, the Smart-Home Diagnostic Decision Tree, or the Home Assistant Error Decoder when the symptom crosses more than one integration.