Troubliq

Smart-home fixes, step by step.

Category: Installation & Networking

Installation and networking guides for Home Assistant backups, restores, DNS, VLANs, multicast, MQTT, Wi-Fi, containers, virtual machines, reverse proxies, certificates, ports, and connectivity. Begin by identifying the installation type and preserving a backup. Backup encryption-key recovery · MQTT entities unavailable after restart.

  • Local Bluetooth adapter does not support passive scanning in Home Assistant

    Local Bluetooth adapter does not support passive scanning in Home Assistant

    Direct answer: The message “Local Bluetooth adapters that do not support passive scanning cannot be configured” usually means Passive mode was requested but the local adapter and software stack cannot expose it. Use Auto or Active, then verify BlueZ 5.63 or later, experimental features, D-Bus access, and VM or container passthrough before replacing hardware.

    This guide applies to local Bluetooth controllers on Home Assistant OS, Supervised, Container, VM, and Core installations. It does not diagnose an ESPHome Bluetooth proxy that is offline because of Wi-Fi, encryption, or proxy firmware.

    Passive scanning only listens to advertisements; active scanning can request additional advertising data. Some devices need active scan responses. Therefore, passive mode is not inherently superior, and fixing this configuration error does not guarantee that every missing Bluetooth device will appear.

    Exact symptoms and what they tell you

    The exact error often appears after selecting Passive explicitly. Home Assistant may still list the controller and may work in Active mode, which is strong evidence that the adapter is functional but the requested capability is unavailable.

    On custom Linux deployments, the hardware may support passive scanning while the host BlueZ version, experimental-feature setting, D-Bus exposure, or container permissions prevent Home Assistant from using it.

    A completely missing adapter is a lower-level problem. A present adapter with only one undiscovered device is usually an integration, encryption, active-scan, pairing, or radio-coverage problem rather than this exact capability error.

    Before making changes

    Record the selected scan mode, adapter chipset, installation type, Home Assistant and OS versions, kernel, BlueZ version, VM or container mappings, whether Active works, and whether an ESPHome proxy sees the device.

    Do not remove every Bluetooth integration, factory-reset devices, grant unlimited container privileges, or buy a dongle before locating the failed layer. A new adapter cannot repair missing D-Bus or passthrough.

    Diagnostics may contain adapter addresses, nearby-device identifiers, device names, network details, bind keys, and account information. Review and redact them before sharing.

    Ranked diagnostic workflow

    1. Return the scanner to Auto

    Why this branch ranks here: Official documentation states that Auto can fall back to Active when passive scanning is unsupported.

    Least-destructive diagnostic: Open Settings → Devices & services → Bluetooth, select the affected local adapter, and replace forced Passive with Auto. Reload once if requested.

    How to interpret the result: If the setting saves and the error disappears, the adapter is usable and the failure was specifically forced passive mode.

    Verified repair: Keep Auto unless a documented device or integration requirement justifies another mode.

    Rollback: Return to the recorded mode if normal discovery becomes worse.

    2. Test Active mode

    Why this branch ranks here: Some devices need scan-response data that passive listening cannot obtain.

    Least-destructive diagnostic: Select Active temporarily, restart Home Assistant once if required, and observe the adapter plus one known device near it.

    How to interpret the result: Active working confirms that the controller and basic host path function. Failure in both modes moves attention to hardware, drivers, passthrough, or host services.

    Verified repair: Use Active for integrations that require scan responses, or Auto for general compatibility.

    Rollback: Return to Auto if permanent Active is unnecessary or less stable.

    3. Confirm the controller exists

    Why this branch ranks here: Scan-mode diagnosis is premature when the local adapter is absent.

    Least-destructive diagnostic: Inspect the Bluetooth integration and system hardware for the expected controller. Confirm that it remains present after one normal restart.

    How to interpret the result: No adapter indicates USB, host-driver, Bluetooth-service, power, or passthrough trouble. A stable adapter narrows the problem to capabilities and configuration.

    Verified repair: Correct physical detection or passthrough before changing scanner modes.

    Rollback: Undo only the last mapping or USB change if the controller disappears.

    4. Verify BlueZ support

    Why this branch ranks here: Linux passive scanning depends on the Bluetooth stack as well as the chipset.

    Least-destructive diagnostic: Confirm BlueZ 5.63 or later and experimental features when passive scanning is required. Home Assistant OS 9.4 and later includes the documented support path.

    How to interpret the result: An old or incomplete BlueZ environment explains why Passive is unavailable even when a chipset specification suggests support.

    Verified repair: Use the supported host upgrade and BlueZ configuration method for the installation.

    Rollback: Restore the prior Bluetooth-service configuration if the service no longer starts.

    5. Check D-Bus visibility

    Why this branch ranks here: Home Assistant controls BlueZ and reads scanner capabilities through D-Bus.

    Least-destructive diagnostic: Confirm the required host D-Bus socket and Bluetooth interfaces are visible to Home Assistant or its container.

    How to interpret the result: Missing interfaces identify a host/container boundary, not a reason to factory-reset devices or assume the dongle is dead.

    Verified repair: Expose only the documented D-Bus access required by the supported deployment.

    Rollback: Remove overly broad mappings and restore the secure configuration if they were unnecessary.

    6. Audit container mappings

    Why this branch ranks here: A container can display partial Bluetooth information while lacking required device or bus capabilities.

    Least-destructive diagnostic: Compare the deployment with current Home Assistant Container Bluetooth requirements and verify the controller plus D-Bus mappings.

    How to interpret the result: Capabilities appearing after the corrected mapping confirm deployment configuration as the cause.

    Verified repair: Keep narrow explicit mappings; do not leave privileged mode enabled as a blind workaround.

    Rollback: Restore the last known-good compose or container definition if the change fails.

    7. Verify VM USB ownership

    Why this branch ranks here: The host or hypervisor may retain the controller or detach it after reboot.

    Least-destructive diagnostic: Attach the Bluetooth controller exclusively to the Home Assistant guest and configure persistent reconnection.

    How to interpret the result: If the host still owns the adapter, the guest cannot expose reliable scanner capabilities. Intermittent attachment explains changing behavior.

    Verified repair: Create stable passthrough for a dedicated adapter.

    Rollback: Return ownership to the original system if Home Assistant is not intended to control it.

    8. Distinguish local adapters from proxies

    Why this branch ranks here: Local BlueZ scanner modes and ESPHome Bluetooth proxy settings use different paths.

    Least-destructive diagnostic: Use Bluetooth diagnostics to identify which scanner hears the target device and whether the failing scanner is local or remote.

    How to interpret the result: A working proxy with a failing local controller isolates the local host. A failing proxy requires Wi-Fi, firmware, encryption, and coverage checks.

    Verified repair: Configure each scanner through its own documented integration.

    Rollback: Do not delete a working scanner while testing another.

    9. Check active-scan requirements

    Why this branch ranks here: Many devices advertise limited data until a scanner sends an active request.

    Least-destructive diagnostic: Review the target integration documentation and test the device near the scanner in Active mode.

    How to interpret the result: Discovery only in Active mode is consistent with a scan-response requirement, not a passive-scanning defect.

    Verified repair: Use Auto or Active and maintain adequate coverage.

    Rollback: Return to Auto after testing when the integration does not require permanent Active.

    10. Investigate kernel or firmware instability

    Why this branch ranks here: Repeated timeouts, failed active scans, or an all-zero controller address can indicate a deeper host problem.

    Least-destructive diagnostic: Capture the earliest concise logs, note kernel and firmware versions, then perform one clean host power cycle after a safe shutdown.

    How to interpret the result: Temporary recovery followed by recurrence supports firmware, kernel, power, or controller instability rather than a UI selection.

    Verified repair: Apply supported stable OS, kernel, and firmware updates after backups.

    Rollback: Use the platform’s supported rollback if the update introduced the fault.

    11. Improve radio placement

    Why this branch ranks here: Interference rarely creates this exact settings error, but it can hide devices after mode configuration is repaired.

    Least-destructive diagnostic: Move USB radios away from USB 3 equipment and metal enclosures; compare discovery and signal close to the target device.

    How to interpret the result: Improvement after relocation proves RF conditions were a second issue. No change sends the investigation back to integration and host support.

    Verified repair: Use a shielded extension or a properly configured Bluetooth proxy for coverage.

    Rollback: Return equipment to the former location if other areas lose coverage.

    12. Replace hardware only with evidence

    Why this branch ranks here: Buying a new controller cannot fix BlueZ, D-Bus, container, or VM problems.

    Least-destructive diagnostic: Confirm the host stack and mappings are correct and that diagnostics still show the needed capability is unsupported.

    How to interpret the result: Persistent lack of support on a healthy stack justifies checking Home Assistant’s current supported-adapter guidance.

    Verified repair: Install supported hardware or a proxy appropriate for the environment, then test across a restart.

    Rollback: Keep the original adapter until the replacement passes sustained device-update checks.

    Verification

    The exact passive-scanning configuration error must disappear, and the adapter must remain available after one controlled restart.

    Verify both ordinary advertisement updates and, when applicable, a device known to need active scan responses. One discovery event is not enough; observe normal updates over time.

    Confirm that no security boundary was broadened unnecessarily and that critical Bluetooth automations still have a manual fallback.

    Recovery and escalation

    If discovery worsens, return to the recorded scan mode and reverse only the last host, container, VM, or hardware change. Do not factory-reset target devices merely because the scanner rejected Passive.

    Escalate with installation type, Home Assistant and OS versions, kernel, BlueZ version, adapter chipset and firmware, selected mode, whether Active and Auto work, whether a proxy works, and short redacted logs.

    Safety and privacy

    Remove Bluetooth addresses, account tokens, bind keys, device names that reveal identity or location, and unrelated diagnostics before posting.

    Shut down cleanly before removing hardware. If Bluetooth controls locks, alarms, heating, medical, or safety-related equipment, maintain independent manual control.

    Prevention

    Leave scanner mode on Auto unless a specific documented need exists. Keep the host Bluetooth stack supported and maintain stable VM or container mappings.

    Place radios away from interference, document the working configuration, and test important Bluetooth automations after Core, OS, kernel, BlueZ, or hypervisor updates.

    Frequently asked diagnostic questions

    Does “return the scanner to auto” mean the hardware is broken?

    Not by itself. This check isolates one layer of the failure. If the setting saves and the error disappears, the adapter is usable and the failure was specifically forced passive mode. Do not replace hardware until the relevant transport, permission, configuration, and software checks agree.

    Does “test active mode” mean the hardware is broken?

    Not by itself. This check isolates one layer of the failure. Active working confirms that the controller and basic host path function. Failure in both modes moves attention to hardware, drivers, passthrough, or host services. Do not replace hardware until the relevant transport, permission, configuration, and software checks agree.

    Does “confirm the controller exists” mean the hardware is broken?

    Not by itself. This check isolates one layer of the failure. No adapter indicates USB, host-driver, Bluetooth-service, power, or passthrough trouble. A stable adapter narrows the problem to capabilities and configuration. Do not replace hardware until the relevant transport, permission, configuration, and software checks agree.

    Does “verify bluez support” mean the hardware is broken?

    Not by itself. This check isolates one layer of the failure. An old or incomplete BlueZ environment explains why Passive is unavailable even when a chipset specification suggests support. Do not replace hardware until the relevant transport, permission, configuration, and software checks agree.

    Does “check d-bus visibility” mean the hardware is broken?

    Not by itself. This check isolates one layer of the failure. Missing interfaces identify a host/container boundary, not a reason to factory-reset devices or assume the dongle is dead. Do not replace hardware until the relevant transport, permission, configuration, and software checks agree.

    Does “audit container mappings” mean the hardware is broken?

    Not by itself. This check isolates one layer of the failure. Capabilities appearing after the corrected mapping confirm deployment configuration as the cause. Do not replace hardware until the relevant transport, permission, configuration, and software checks agree.

    Does “verify vm usb ownership” mean the hardware is broken?

    Not by itself. This check isolates one layer of the failure. If the host still owns the adapter, the guest cannot expose reliable scanner capabilities. Intermittent attachment explains changing behavior. Do not replace hardware until the relevant transport, permission, configuration, and software checks agree.

    Does “distinguish local adapters from proxies” mean the hardware is broken?

    Not by itself. This check isolates one layer of the failure. A working proxy with a failing local controller isolates the local host. A failing proxy requires Wi-Fi, firmware, encryption, and coverage checks. Do not replace hardware until the relevant transport, permission, configuration, and software checks agree.

    Does “check active-scan requirements” mean the hardware is broken?

    Not by itself. This check isolates one layer of the failure. Discovery only in Active mode is consistent with a scan-response requirement, not a passive-scanning defect. Do not replace hardware until the relevant transport, permission, configuration, and software checks agree.

    Does “investigate kernel or firmware instability” mean the hardware is broken?

    Not by itself. This check isolates one layer of the failure. Temporary recovery followed by recurrence supports firmware, kernel, power, or controller instability rather than a UI selection. Do not replace hardware until the relevant transport, permission, configuration, and software checks agree.

    Does “improve radio placement” mean the hardware is broken?

    Not by itself. This check isolates one layer of the failure. Improvement after relocation proves RF conditions were a second issue. No change sends the investigation back to integration and host support. Do not replace hardware until the relevant transport, permission, configuration, and software checks agree.

    Does “replace hardware only with evidence” mean the hardware is broken?

    Not by itself. This check isolates one layer of the failure. Persistent lack of support on a healthy stack justifies checking Home Assistant’s current supported-adapter guidance. Do not replace hardware until the relevant transport, permission, configuration, and software checks agree.

    Related Troubliq resources

    Use Bluetooth Proxy unavailable for proxy transport problems, BTHome device not discovered for BTHome discovery, and the Error Decoder for exact messages.

    Evidence and testing status

    Last reviewed: September 28, 2026. Testing disclosure: Scanner-mode behavior and Linux support requirements were checked against current Home Assistant Bluetooth documentation. Troubliq did not reproduce every adapter, BlueZ build, kernel, container, hypervisor, or Bluetooth device.

  • Home Assistant 2026.9 “Could Not Load Home Assistant”: Safe Recovery Checklist

    Home Assistant 2026.9 “Could Not Load Home Assistant”: Safe Recovery Checklist

    Quick answer: If Home Assistant shows “Could not load Home Assistant” after a 2026.9 update, do not immediately reinstall or delete the database. First determine whether the failure is limited to the browser, the frontend, the network path, or Home Assistant Core itself. Test the local IP address, check Core and Supervisor logs, preserve a backup, and only then consider a rollback or restore.

    This guide is designed as a safe diagnostic sequence. The same message can be caused by several different failures, so there is no single universal fix. A recent public issue report describes the message after upgrading to Home Assistant 2026.9.0, but that report alone does not prove that every occurrence has the same cause.

    Two-minute triage

    1. Open Home Assistant through its local IP address, for example http://192.168.1.50:8123, instead of a bookmark, reverse proxy, or cloud URL.
    2. Try a private or incognito browser window. If that works, clear only the stored site data for the Home Assistant address rather than clearing the entire browser.
    3. Try a second device on the same local network.
    4. If the Companion App fails but a browser works, reset the app’s frontend cache and confirm its internal URL.
    5. If no local device can connect, inspect Core, Supervisor, host, and network status before changing configuration.

    Step 1: Separate a frontend problem from a Core problem

    A browser error does not necessarily mean Home Assistant Core is down. The frontend can fail to load because of stale cached JavaScript, a custom dashboard resource, a reverse-proxy error, an invalid certificate path, or an address that no longer points to the correct host.

    Use three tests:

    • Local IP works, external address fails: investigate the reverse proxy, DNS, certificate, Cloudflare tunnel, or router forwarding.
    • One browser fails, another works: investigate browser storage, cached frontend files, extensions, or an old pinned shortcut.
    • Every local client fails: move to Core, Supervisor, and host diagnostics.

    Step 2: Confirm the machine is reachable

    Check the router’s client list and confirm that the Home Assistant machine still has the expected IP address. A DHCP change can make an old bookmark fail even when Home Assistant is healthy. Reserve the address in the router after access is restored.

    If you use Home Assistant OS and can reach the local console, check that the host has an address and that the Core container is running. Useful read-only commands include:

    ha network info
ha core info
ha supervisor info
ha core logs

    Do not publish logs without removing tokens, public IP addresses, email addresses, device identifiers, and location information.

    Step 3: Read the first meaningful error, not the last repeated error

    Repeated reconnect messages are often symptoms. Look earlier in the log for the first exception after startup. Record:

    • Home Assistant Core version
    • Home Assistant OS or Container installation type
    • Supervisor version
    • Whether the failure began immediately after an update
    • The first integration or component named in the traceback
    • Database, disk-space, memory, or port-binding errors

    Common branches include a custom integration failing during startup, a database migration taking longer than expected, insufficient storage, a reverse-proxy configuration error, and a frontend resource that is incompatible with the new release.

    Step 4: Check storage and database health

    A nearly full disk can prevent updates, database writes, log rotation, and container startup. If the host reports critically low free space, remove obsolete backups or unused add-on data through supported interfaces. Do not delete database files simply to regain access.

    If the log mentions a malformed SQLite database, follow a database-specific recovery process and preserve copies before making changes. A slow database migration can also make the frontend appear unavailable; repeatedly cutting power during that work increases risk.

    Step 5: Isolate custom integrations and frontend resources

    If the problem began immediately after an update and the log names a custom component, check that component’s release notes and issue tracker. Disable only the named component when you have a backup and a reversible method. Do not remove the entire custom_components directory as a first response.

    For dashboard failures, test the default Overview dashboard. A broken custom card can stop a particular dashboard from rendering while the rest of Home Assistant remains functional.

    Step 6: Check reverse-proxy and URL settings

    If local access works, the Home Assistant update may be unrelated to the external failure. Verify that the proxy still sends WebSocket traffic, preserves the correct host, and points to the current local address and port. Compare the browser’s error with the Home Assistant HTTP logs.

    Do not add broad trusted_proxies ranges just to make an error disappear. Trust only the actual proxy address or narrowly required subnet. An overly broad trusted range weakens the protection against spoofed forwarding headers.

    Step 7: Restart once, then stop repeating restarts

    A single controlled Core restart is reasonable after logs have been collected. Repeated restarts can hide the first error, interrupt migrations, and make troubleshooting harder. If Core repeatedly becomes unavailable, preserve the logs from one complete startup cycle.

    When a rollback is appropriate

    Consider rollback only when all of the following are true:

    • The failure started directly after the update.
    • Local access and logs indicate a Core regression rather than a network or browser problem.
    • You have a recent backup from before the update.
    • You understand that restoring a backup also restores its older configuration and database state.

    Prefer Home Assistant’s supported backup restore workflow. If the current patch release contains a confirmed fix, updating forward may be safer than returning to an older release. Review the release notes and the relevant issue before deciding.

    Do not do these things first

    • Do not reinstall Home Assistant before preserving backups and logs.
    • Do not delete home-assistant_v2.db unless the logs identify database corruption and you have a recovery copy.
    • Do not expose port 8123 directly to the internet to test connectivity.
    • Do not paste access tokens or complete diagnostics into public forums.
    • Do not assume every “Could not load” screen is the same 2026.9 bug.

    Decision tree

    1. Does the local IP work? If yes, troubleshoot the external URL, proxy, DNS, or certificate.
    2. Does another browser work? If yes, clear site-specific browser data and inspect extensions.
    3. Is Core running? If no, inspect Core and Supervisor logs.
    4. Is the disk nearly full? If yes, free space safely before another update attempt.
    5. Does the first traceback name a custom component? If yes, check that component’s compatibility and disable only that component.
    6. Did the failure begin exactly with 2026.9 and survive local/browser checks? Preserve a backup and compare the active issue reports before rolling back or updating forward.

    Information to collect before asking for help

    • Exact Core, Supervisor, and OS versions
    • Installation type
    • Local versus external access results
    • First relevant traceback with private information removed
    • Available disk space
    • Whether custom integrations are installed
    • Whether the problem persists on a default dashboard

    Sources and status

    This guide uses a current public issue report as an incident signal, not as proof of a universal defect: Home Assistant Core issue #181212. For backup and recovery procedures, use the current Home Assistant backup documentation. Check the issue and release notes for changes before applying version-specific advice.

    Last reviewed: September 23, 2026. Troubleshooting guidance may change as Home Assistant publishes patch releases.

    Additional evidence-based diagnostics

    Check the HTTP path without changing it

    Use a browser developer network panel only to observe the first failed request. A 401 or 403 points toward authentication or proxy policy; a 404 toward an incorrect path or stale frontend asset; a 502 or 504 toward the proxy-to-Core path; and a browser certificate error toward TLS. Record the status and URL, but do not publish tokens or query strings.

    Distinguish startup delay from a crash loop

    After an update, database migrations and integration setup can extend startup. Watch Core status and logs instead of repeatedly restarting. A single long startup that completes differs from a process that exits and restarts. For a crash loop, capture the first exception in each cycle and the exit reason.

    Use Safe mode only as evidence

    If Home Assistant offers Safe mode and it loads, the frontend and core platform are capable of starting with custom integrations and custom frontend resources restricted. That result makes custom code a stronger suspect; it does not identify which component failed. Re-enable components selectively after reviewing logs and backups.

    Check custom dashboard resources

    A custom card or JavaScript module can break one dashboard after a frontend update. Open the default Overview dashboard directly and inspect browser console errors. Update or disable only the named resource. Avoid deleting dashboard storage or all HACS content as a broad test.

    Inspect authentication state

    If the login page loads but the interface fails after authentication, compare a private window, another user, and the same local URL. Repeated failed logins, an incorrect system clock, or proxy header problems can affect sessions. Do not disable authentication or widen trusted networks.

    Evaluate storage pressure

    Check free space, database size, backup accumulation, and host I/O errors. Free space through supported backup and add-on interfaces. Preserve recent backups externally before removing old local copies. Filesystem errors or recurring read-only remounts require storage replacement or host repair, not repeated Core restarts.

    Expected-result matrix

    Local IP success with external failure confirms Core is reachable and shifts attention to DNS, proxy, TLS, or tunnel. Safe mode success shifts attention to custom code. Core running with frontend asset errors points to browser or resource delivery. Core repeatedly stopping points to the first backend exception or host resource failure.

    Recovery verification

    After a fix, load the login page and dashboard from a clean browser session, confirm live entity updates, open Settings and Logs, restart Core once, and retest the intended external path. Verify that the canonical configuration remains secure and that no emergency bypass is left enabled.

    Escalation evidence

    Provide Core, Supervisor and OS versions, installation type, the exact time and first exception, local-versus-external results, disk availability, and whether Safe mode loads. Redact tokens, public addresses, coordinates, camera endpoints, device identifiers and personal account data.

    Testing disclosure

    Troubliq has not reproduced every 2026.9 failure environment. The workflow combines official recovery practices with the cited public incident report and treats that report as evidence of one occurrence, not proof of a universal release defect.

    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

    Browser console interpretation

    A failed JavaScript chunk with an old hashed filename often indicates cached frontend assets. A blocked WebSocket after successful HTML delivery points toward proxy upgrade handling, authentication or network policy. Repeated 401 responses point to session state; 404 responses for custom-card resources point to dashboard dependencies. Capture only the error type and resource name, not authentication headers.

    Installation-type branches

    On Home Assistant OS, use the local console, Supervisor and supported backup tools. In Container, inspect the container state, logs, volume mounts and image version without using Supervisor commands. In Core environments, inspect the Python service and virtual environment. Applying commands for the wrong installation type can create a second failure.

    Update-forward decision

    Before restoring, read the current patch release notes and the cited issue status. A fixed patch preserves newer database state and is often safer than rollback. Update forward only after a backup and only when the fix matches the observed component or symptom; a generic newer version is not proof of relevance.

    Rollback decision

    Rollback is justified when the previous version was stable, the failure begins immediately after updating, logs support a regression, and a compatible pre-update backup exists. Record configuration changes made since that backup. Restoring also rolls back database history and configuration, so preserve the current backup separately.

    External-path verification

    When local access works, test DNS resolution, certificate hostname and expiry, proxy health, upstream address, WebSocket upgrade and firewall rules. Change one layer at a time. Do not expose port 8123 publicly, disable TLS verification, or trust a broad network range to make a diagnostic test pass.

  • Home Assistant 400 Bad Request behind a reverse proxy: trusted proxy fix

    Home Assistant 400 Bad Request behind a reverse proxy: trusted proxy fix

    Direct answer: If local access works but the proxied URL returns “400: Bad Request,” check the Home Assistant log for “A request from a reverse proxy was received … but your HTTP integration is not set-up for reverse proxies.” Configure `use_x_forwarded_for: true` and trust only the actual proxy address or the narrow network that Home Assistant sees. Then validate the configuration and restart Home Assistant. Do not trust the entire internet or disable proxy protections.

    This guide addresses a Home Assistant 400 Bad Request error behind a reverse proxy. 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 external hostname returns 400 while the local IP works.
    • Logs identify a request from a reverse proxy that is not configured.
    • The error began after moving NGINX, Traefik, Caddy, Cloudflare Tunnel, Docker networks, or Home Assistant.
    • HTTPS terminates at the proxy but Home Assistant sees the wrong scheme or client address.
    • Changing YAML appears to do nothing until Home Assistant is restarted.

    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. `use_x_forwarded_for` is missing or false.
    • 2. `trusted_proxies` does not contain the source address Home Assistant actually sees.
    • 3. A container or add-on changed its internal IP or network range.
    • 4. YAML indentation or placement is wrong, so the `http:` configuration is not loaded.
    • 5. The proxy is not sending valid X-Forwarded-For or X-Forwarded-Proto headers.
    • 6. Multiple proxy hops exist, but the trusted chain is incomplete or overly broad.

    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

    Confirm the pattern before editing: test the local Home Assistant URL and the external hostname. Record the time and inspect Settings → System → Logs. The key message normally includes the source IP Home Assistant sees. If local access also fails, investigate a broader outage instead of assuming proxy trust.

    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

    Make a full backup and copy the existing `http:` configuration. Search configuration.yaml and included files for another `http:` block; YAML cannot safely define the same mapping twice. Note whether a proxy add-on, separate container, NAS, tunnel, or load balancer sits directly in front of Home Assistant.

    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

    Use the log-reported source address to identify the immediate proxy hop. In Docker, this is often a container-network address rather than the LAN address or public visitor address. Trust the narrowest stable address or CIDR justified by your design. Never add 0.0.0.0/0 or ::/0.

    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

    Configure the HTTP integration with `use_x_forwarded_for: true` and a `trusted_proxies:` list. Preserve correct YAML indentation and quote values only when appropriate. The trusted entry represents the proxy that connects to Home Assistant, not every remote client that uses the proxy.

    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

    Validate configuration before restarting. Use Developer Tools → YAML → Check configuration or the supported validation method for your installation. A syntax error can prevent startup. If validation fails, restore the previous block and correct the exact line rather than experimenting on the live system.

    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

    Restart Home Assistant fully; reloading YAML alone may not reload the HTTP integration. Keep local access available during the test so a proxy mistake does not lock you out. After restart, test the external URL in a private browser session and examine new logs.

    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

    Verify the proxy forwards Host, X-Forwarded-For, X-Forwarded-Proto, and WebSocket upgrade headers correctly for your proxy product. Follow that product’s official Home Assistant example. Do not pass arbitrary client-controlled forwarding headers without sanitizing them at the trusted edge.

    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

    If Cloudflare Tunnel or another layered service is involved, map every hop: client → edge → connector/proxy → Home Assistant. Home Assistant must trust its immediate source, and the trusted proxy must construct the forwarding chain safely. Avoid broad ranges copied from unrelated examples.

    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

    NGINX Proxy Manager or separate NGINX container: use the address or subnet of the container network Home Assistant sees, not automatically the NAS LAN address.

    Container, network, or account variation

    Home Assistant add-on proxy: use the add-on documentation because Supervisor-managed networks differ from standalone Docker.

    Partial failure versus complete failure

    Cloudflare Tunnel: determine whether cloudflared connects directly or through another proxy and retain authenticated, encrypted origin access.

    Multi-device or multi-hop environments

    Synology or other NAS reverse proxy: confirm the NAS source address, WebSocket support, certificate path, and whether another container hop changes the source.

    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

    A successful repair has several parts: the external hostname loads without 400; login and WebSockets remain connected; the Home Assistant log no longer reports an untrusted reverse proxy; generated URLs use HTTPS; and local access still works. Check that failed login records show the real client address rather than only the proxy when your chain is designed to preserve it. Test after a proxy or container restart to ensure the trusted address remains stable.

    • 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

    If Home Assistant fails after editing YAML, restore the saved `http:` block through local file access or a backup, validate, and restart. If external access fails but local access works, revert only the proxy-related change. Do not expose port 8123 publicly as an emergency shortcut. Keep a local administrative path and a tested backup before changing remote access.

    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

    • Reserve or define stable proxy networks where supported.
    • Keep trusted proxy ranges narrow and documented.
    • Validate YAML before every restart.
    • Test WebSockets and real client IP handling after proxy upgrades.
    • Maintain secure local access for recovery.
    • Review the proxy chain whenever containers, tunnels, or networks move.

    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 a Home Assistant 400 Bad Request error behind a reverse proxy, 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 external hostname returns 400 while the local IP works

    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: Logs identify a request from a reverse proxy that is not configured

    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 error began after moving NGINX, Traefik, Caddy, Cloudflare Tunnel, Docker networks, or Home Assistant

    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: HTTPS terminates at the proxy but Home Assistant sees the wrong scheme or client address

    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: Changing YAML appears to do nothing until Home Assistant is restarted

    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: Scott Rodgerson 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.

    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.

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

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

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

    Symptoms and scope

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

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

    What the emergency kit contains

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

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

    Before attempting another restore

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

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

    Step 1: Confirm that the prompt is for backup encryption

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

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

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

    If the original Home Assistant installation is accessible:

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

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

    Step 3: Search likely safe locations methodically

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

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

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

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

    Step 4: Check the configured backup destination

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

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

    Step 5: Match the kit to the backup

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

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

    Step 6: Verify backup integrity before blaming the key

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

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

    Step 7: Prepare the destination correctly

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

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

    Step 8: Restore with the correct key

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

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

    How to verify the restored system

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

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

    If you cannot recover the key

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

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

    Rollback and recovery

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

    When to escalate

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

    Prevention: a practical 3-2-1 plan

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

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

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

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

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

    Build a backup recovery drill instead of trusting an untested archive

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

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

    Information to record before requesting help

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

    Sources

    Last reviewed: September 8, 2026.

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

    Decision guide: which recovery path should you choose?

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

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

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

    Find your next troubleshooting path

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

  • ZHA coordinator keeps disconnecting with NCP entered failed state

    ZHA coordinator keeps disconnecting with NCP entered failed state

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

    Symptoms

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

    Prerequisites

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

    Diagnostic steps

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

    Verify the fix

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

    Recovery and rollback

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

    Prevention

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

    Sources

    Last reviewed: September 4, 2026.

    Related Troubliq guides

    Find your next troubleshooting path

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

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

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

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

    Network tests that prove the failing layer

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

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

    Configuration comparison procedure

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

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

    Power, radio, and timing checks

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

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

    Log-reading workflow

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

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

    Safe change order

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

    Post-repair validation

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

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

    When to stop and escalate

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

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

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

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

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

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

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

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

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

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

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

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

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

    Identify what “NCP failed” means for this coordinator

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

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

    Check power and USB behavior safely

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

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

    Prove that the Zigbee network recovered

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

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

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

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

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

    What “on Wi-Fi but offline” actually means

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

    Before changing anything

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

    1. Confirm the device is truly online

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

    2. Test the address Home Assistant is using

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

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

    3. Check the native API path

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

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

    4. Verify API configuration and encryption

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

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

    5. Read live logs before restarting

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

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

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

    6. Check for duplicate device names

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

    7. Restart in the least-destructive order

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

    How to verify the fix

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

    If it still fails

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

    Official references

    Last reviewed: September 5, 2026.

    Related Troubliq guides

    Find your next troubleshooting path

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

    Confirm the exact failure boundary

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

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

    Verify addressing and name resolution

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

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

    Check API credentials without exposing secrets

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

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

    Use logs before reflashing

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

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

    Verify the repair over time

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

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

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

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

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

    Network tests that prove the failing layer

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

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

    Configuration comparison procedure

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

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

    Power, radio, and timing checks

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

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

    Log-reading workflow

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

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

    Safe change order

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

    Post-repair validation

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

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

    When to stop and escalate

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

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

  • All Matter devices unavailable in Home Assistant

    All Matter devices unavailable in Home Assistant

    Quick diagnosis

    Direct answer: If all Matter devices are unavailable in Home Assistant, investigate the shared Matter Server and local IPv6 path before resetting any accessory. When only one device is unavailable, focus on that device’s power, Wi-Fi or Thread path, firmware, and fabric record. Do not remove or factory-reset devices until the shared layers are proven healthy.

    Try this first: Confirm the device has power and still works in its native app → check whether other Matter devices are also unavailable → verify the Matter Server is running → then check IPv6, multicast, Wi-Fi or Thread reachability.

    Important: If the device works in another ecosystem but not Home Assistant, concentrate on the Home Assistant/Matter Server path rather than immediately re-pairing the accessory.

    Applies to

    Home Assistant installations using the Matter integration with Wi-Fi or Thread devices. Menu names and behavior can change between releases; record your Home Assistant Core, Matter Server, border-router, and device firmware versions.

    1. Preserve the working evidence

    • Do not factory-reset or remove the device yet.
    • Save the exact Home Assistant error and the time it occurred.
    • Check whether one Matter device or every Matter device is unavailable.
    • Note any router, VLAN, firewall, border-router, credential, or software change.

    2. Separate device failure from controller failure

    Confirm that the device has power. If its manufacturer app can still control it, the device and at least one control path are alive. If all Matter devices fail together, investigate Home Assistant, Matter Server, and the network before individual devices.

    3. Check Home Assistant services

    Open Settings, then Devices & services. Confirm that the Matter integration is loaded and inspect its messages. Check the Matter Server add-on or service logs around the recorded failure time. Restart only the affected service once, then wait for discovery to settle before retesting.

    4. Verify local network reachability

    Matter depends on local IPv6 and multicast discovery. Confirm that Home Assistant and the device network can exchange local traffic. Guest isolation, client isolation, blocked multicast, strict VLAN rules, or a recent router change can break an otherwise valid pairing. Avoid broad firewall changes; test the smallest reversible rule and restore it if the result does not change.

    5. For Thread devices

    Confirm that the expected Thread border router is online and that Home Assistant is using the intended Thread credentials. Do not create a new Thread network simply because a device is unavailable; duplicate networks can make diagnosis harder.

    6. Re-interview before re-pairing

    After power, services, network, and border-router checks, reboot only the affected low-voltage device if its manufacturer instructions allow it. Removal and factory reset are last resorts because they can erase credentials and automations.

    Escalate safely

    Stop for overheating, swelling batteries, damaged wiring, smoke, sparks, or water near electricity. For a repeatable software failure, collect redacted logs, versions, device model, and the smallest reproduction before asking the manufacturer or Home Assistant community for help.

    Official sources

    Last reviewed: September 4, 2026.

    Find your next troubleshooting path

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

    Confirm where “unavailable” begins

    Treat pairing and availability as separate stages. A successful Matter commission proves that the controller exchanged credentials and added the accessory to a fabric; it does not prove that Home Assistant can continue reaching the device afterward. Note whether the accessory becomes unavailable immediately, after several minutes, after a router restart, or only after Home Assistant restarts. That timing narrows the problem before you change anything.

    Check whether the same accessory remains controllable from another authorized ecosystem. If it works there but not in Home Assistant, focus on Home Assistant’s Matter integration and the path to its Matter server. If it disappears everywhere, focus on power, Wi-Fi or Thread connectivity, the border router, and the accessory itself. Do not remove it from every controller just to perform this comparison.

    Preserve evidence before re-pairing

    Open the device page and record the exact availability state, diagnostic entities, firmware version, and the time of the last successful update. Save relevant Matter Server and Home Assistant logs around that timestamp. Redact fabric identifiers, Wi-Fi credentials, setup codes, certificates, tokens, and public IP addresses before sharing logs.

    Create a current Home Assistant backup before changing integrations or deleting devices. Also record which ecosystem commissioned the device first and whether multi-admin sharing was used. Those ownership details matter because removing the accessory from the wrong controller can invalidate the sharing path and turn a recoverable connectivity problem into a new commissioning problem.

    Check the Matter server and integration

    If the problem started after updating Home Assistant 2026.9, also use our Matter Network Map missing or unsupported diagnostic to separate a Core-version issue from a Matter Server or fabric-visibility issue.

    Verify that the Matter integration is loaded and that its server is running without a repeating connection or startup error. A restart may temporarily hide a race or network problem, so use it as a controlled test rather than assuming that a successful restart is a permanent repair. After restarting, observe whether the device returns on its own and how long it stays available.

    Compare the device’s unavailable timestamp with Home Assistant Core, Matter Server, add-on, container, or host restarts. If many Matter devices fail together, investigate the shared server and network path first. If one device fails while the rest remain stable, prioritize that accessory’s power, firmware, radio path, and individual fabric record.

    Verify local network requirements

    Matter depends on reliable local IP communication. Confirm that Home Assistant, the Matter server, the accessory, and any Thread border router can participate in the required local network traffic. VLAN rules, client isolation, multicast filtering, broken IPv6, or a container network change can allow commissioning to begin yet prevent dependable operation afterward.

    Do not open inbound internet ports as a troubleshooting shortcut. Matter control is designed around authenticated local communication, and exposing Home Assistant or the Matter server does not repair local discovery. Test temporary firewall or VLAN changes narrowly, document them, and restore the original policy after each comparison.

    Separate Wi-Fi Matter from Thread Matter

    For a Wi-Fi Matter accessory, confirm that it still has power, a valid lease, and a stable connection to the intended SSID. Check for band steering, access-point roaming, client isolation, or DHCP changes near the time of failure. A reservation can make diagnosis easier, but do not assume that changing the address alone fixes the underlying reachability problem.

    For a Thread accessory, verify that at least one compatible Thread border router is online and that the Thread network used during commissioning is still available. More border routers do not automatically repair mismatched credentials or separate Thread networks. Confirm the network identity before resetting, migrating, or creating a new Thread network.

    Use a controlled recovery sequence

    Start with the least disruptive action: restore power or network reachability, wait for reconnection, reload only the affected integration if appropriate, and then restart the smallest relevant service. Test the device after each action. Changing several layers at once removes the evidence needed to identify what actually restored availability.

    Re-interviewing, removing, or factory-resetting the device belongs near the end of the sequence. Before removal, check whether dashboards, scenes, automations, and voice assistants depend on the current entity and device identifiers. A newly commissioned record may not preserve those references even when the physical accessory is the same.

    Verify the repair

    After the device returns, test control and state reporting from Home Assistant several times. Then restart the accessory if practical, restart the relevant Matter service during a maintenance window, and observe the device long enough to cover the interval that previously triggered the failure. Availability for a few seconds is not enough evidence of a stable repair.

    Document the confirmed cause, the single change that resolved it, and the versions involved. Keep the backup and sanitized logs until the device survives normal network and service restarts. If the failure returns, that record prevents repeated resets and gives the vendor or Home Assistant community a reproducible starting point.

    When to escalate

    Escalate with a concise evidence package when the accessory repeatedly becomes unavailable after the same event, the Matter server reports a reproducible error, or current firmware does not restore stable operation. Include sanitized log timestamps, Home Assistant and Matter Server versions, accessory model and firmware, connection type, border-router model when applicable, and the controlled tests already completed. This gives the vendor or community enough information to distinguish an accessory defect from a platform or network regression without asking you to reset the device again.

    Detailed evidence checklist for Matter device pairs but shows unavailable in Home Assistant

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

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

    Network tests that prove the failing layer

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

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

    Configuration comparison procedure

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

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

    Power, radio, and timing checks

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

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

    Log-reading workflow

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

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

    Safe change order

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

    Post-repair validation

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

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

    When to stop and escalate

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

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