Smart-home fixes, step by step.

Category: Wi-Fi & Connectivity

Wi-Fi association, signal, roaming, DHCP, DNS, mDNS, isolation, firewalls, internet outages, and local connectivity troubleshooting.

Home Assistant Zigbee Devices Keep Going Offline After a Router or Wi‑Fi Change: What to Check
Quick answer: A Wi‑Fi or router change can affect Zigbee reliability even though Zigbee and Wi‑Fi are different protocols. They share parts of the 2.4 GHz band, so channel overlap, a moved Home Assistant host, USB interference, or a changed power setup can expose a weak mesh. Diagnose one layer at a time instead of resetting every device.

Image: James Yarema / Unsplash

1. Identify what changed

Write down whether the problem began immediately after replacing the router, changing Wi‑Fi channels, moving the Home Assistant computer, changing USB ports, or losing power. Note whether all Zigbee devices fail together or only battery-powered devices in one area. A simultaneous outage points toward the coordinator, integration, host or radio environment; isolated failures more often suggest routing, battery or signal issues.

2. Check the Zigbee coordinator and integration
- In Home Assistant, open the relevant integration (ZHA or Zigbee2MQTT) and confirm it is loaded and the coordinator is available.
- Check the integration logs for serial-port errors, repeated reconnects, adapter resets or MQTT connection failures.
- If the coordinator is USB-connected, check that its stable device path is still present and that the host has not moved it to a different port.
- Use a USB extension cable to move the radio away from the computer, USB 3 devices and metal enclosures if interference is plausible.
3. Consider Wi‑Fi and Zigbee channel overlap

Do not change channels blindly. First record the current Zigbee channel and the router’s 2.4 GHz channel. Nearby networks, channel width and actual radio conditions matter. If you decide to change the Zigbee channel, check the documentation for your coordinator and integration first: some devices may need special handling or rejoining, and a channel change can create a second problem if done casually.

4. Check the mesh before re-pairing

Make sure mains-powered Zigbee routers—such as compatible smart plugs or bulbs—are powered and have had time to rejoin. A powered-off router can strand battery sensors that depended on it. Test a nearby device and a distant device separately. Replace a weak battery only when the evidence points to that device; do not delete devices from the entity registry just because they are temporarily unavailable.

5. Verify recovery
1. Make one change at a time.
2. Watch the integration logs and device availability for several minutes.
3. Test both a nearby and a distant device.
4. Record the fix and any channel or coordinator changes.
When to escalate

If the coordinator repeatedly disconnects, capture the relevant log lines and identify your integration (ZHA or Zigbee2MQTT), coordinator model, host type and what changed before the outage. Avoid posting network keys or other secrets. Those details make the next diagnostic step much more reliable.

Related guides: If Zigbee devices were already dropping offline, see the Zigbee offline diagnosis guide. If several kinds of Home Assistant devices are affected, start with the broader offline checklist. If the issue began after a power cut, use the power-outage recovery guide.

Image credit: James Yarema on Unsplash. This guide is general troubleshooting advice; exact menus and options vary by Home Assistant version and coordinator.
October 16, 2026
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 Bluetooth documentation
- Bluetooth troubleshooting
September 28, 2026
BTHome device not discovered in Home Assistant: Bluetooth troubleshooting
Direct answer: BTHome discovery depends on receiving compatible Bluetooth advertisements; pairing the sensor to a phone is not enough. First verify the device is broadcasting BTHome data, move it close to a known-working Home Assistant Bluetooth adapter or proxy, and confirm the Bluetooth integration is healthy. Then check encryption, duplicate integrations, passive scanning, battery state, and whether a phone connection is suppressing advertisements. Do not delete working Bluetooth devices or reset the sensor until reception is proven.
This guide addresses a BTHome sensor that Home Assistant cannot discover. 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 BTHome setup dialog reports that no devices were found.
- The sensor appears in a vendor app but never in Home Assistant discovery.
- A previously discovered sensor disappears after deletion and does not return.
- The device is visible near one proxy but unavailable through another.
- Measurements freeze even though the sensor display continues to change.
Most likely causes, ranked
Start with the causes that fit the evidence. Do not apply every fix at once: simultaneous changes make it impossible to know what solved the problem and can create a second failure.
- 1. The device is not using BTHome firmware or its broadcast mode is disabled.
- 2. The advertisement is encrypted and Home Assistant lacks the correct bind key.
- 3. The sensor is connected actively to a phone or vendor app and is no longer advertising as expected.
- 4. The adapter or Bluetooth proxy is unavailable, overloaded, too far away, or suffering 2.4 GHz interference.
- 5. Passive scanning, duplicate Bluetooth software, container permissions, or host hardware prevents reception.
- 6. The battery is weak, the advertising interval is long, or the device uses a model-specific activation sequence.
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
Identify the exact device model, firmware, and broadcasting format. A Bluetooth device is not automatically a BTHome device. Consult the manufacturer or firmware project documentation and confirm BTHome support, broadcast version, encryption status, and any button sequence needed to enable advertising.
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
Open Settings → Devices & Services → Bluetooth and confirm at least one scanner is healthy. Review the Bluetooth integration diagnostics and advertisements rather than assuming the host adapter works because another operating-system tool can see a name. Home Assistant needs usable BLE advertisements.
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
Move the sensor within one or two meters of a confirmed scanner or ESPHome Bluetooth proxy for a controlled test. Remove it from metal cabinets and away from USB 3 devices, Wi-Fi access points, and dense wiring. Wait longer than the configured advertising interval.
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
Close the vendor app and disconnect any phone that may hold an active BLE connection. Some devices reduce or stop advertisements during a connection. Disable phone Bluetooth briefly only as a test; do not unpair or reset until you know a phone connection is the cause.
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
Replace or test the battery when voltage is uncertain. Clean battery contacts and confirm polarity. A display can remain alive at a voltage too low for reliable radio transmission. After replacement, allow the device to complete its boot and advertisement cycle.
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
If encryption is enabled, obtain the bind key through the supported manufacturer or firmware process and enter it only in the proper integration flow. Never paste private keys into a public forum or screenshot. A wrong key may allow discovery while preventing useful measurements.
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
Check for duplicate ownership. HACS BLE monitors, vendor integrations, operating-system services, or another Home Assistant instance may be consuming or duplicating the same data. Disable only one suspected conflict at a time, document the prior state, and restore it if the test changes nothing.
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
For container installations, verify the supported Bluetooth access method, D-Bus mapping, permissions, and host adapter. For remote coverage, validate each proxy separately. Do not treat a proxy’s online status as proof that it is forwarding advertisements from this location.
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
New device never discovered: verify firmware format, advertising, proximity, and encryption first.
Container, network, or account variation
Deleted device will not return: check ignored discoveries, stale device entries, encryption, and whether the sensor still advertises; avoid deleting registry files manually.
Partial failure versus complete failure
Device works near the host only: improve proxy placement or RF conditions rather than changing the integration.
Multi-device or multi-hop environments
Multiple scanners report unstable data: examine source switching, proxy latency, duplicate integrations, and signal strength before forcing one path.
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
Watch the Bluetooth advertisement monitor or integration diagnostics until the device address or identifier appears repeatedly. Add the discovered BTHome device and confirm several fresh measurement changes, not merely a device card. Walk the sensor back to its intended location and observe it through multiple broadcast intervals. Restart Home Assistant and one proxy at a time; the device should recover without manual reconfiguration. Confirm automations use stable entity IDs and that timestamps continue advancing.
- 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 a reset is necessary, first record the device model, firmware, bind key, calibration, advertising interval, entity IDs, and automation dependencies. Reset according to the device maker’s instructions, then restore BTHome broadcasting and encryption deliberately. If deletion caused the problem, restore from backup before editing internal registries by hand.
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
- Place proxies for coverage, not merely where power is convenient.
- Label and store bind keys securely.
- Avoid running overlapping BLE integrations without a clear reason.
- Use fresh batteries and realistic advertising intervals.
- Keep Bluetooth proxies and Home Assistant versions compatible.
- Document the scanner that normally hears each important sensor.
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 BTHome sensor that Home Assistant cannot discover, 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 BTHome setup dialog reports that no devices were found
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 sensor appears in a vendor app but never in Home Assistant discovery
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: A previously discovered sensor disappears after deletion and does not return
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 device is visible near one proxy but unavailable through another
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: Measurements freeze even though the sensor display continues to change
Confirm when this began and whether it affects one entity, one device, one integration, or the whole installation. Compare the result on the same network and, when relevant, through the alternate path. Then use the matching diagnostic step above. Do not jump to recovery until the observation is repeatable or the logs identify the failing layer.
Frequently asked questions
Should I delete and add everything again?
Usually not. Re-adding can change entity IDs, erase evidence, and hide the original cause. Use it only after backup, documentation, and the narrower checks in this guide.
Can I ignore the error if it starts working again?
A single brief interruption may be harmless, but a recurring error deserves timestamps and logs. Repetition after the same event often reveals a network, storage, power, permission, or token lifecycle problem.
Is updating Home Assistant always the fix?
No. Updates can contain fixes, but they also change dependencies and behavior. Read release notes, back up first, and match the error to a known fix before treating an update as diagnosis.
How much log information should I share?
Share the smallest relevant window around the failure, with secrets and personal data removed. Include versions and the exact action that caused the event. Avoid uploading complete logs publicly.
When should I escalate?
Escalate when safety, important data, repeated corruption, an upstream regression, or an account-side failure is involved, or when the least-destructive checks produce a clear error you cannot resolve.
Sources and review notes
Photo: Tim Witzdam 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.
September 22, 2026
MQTT entities unavailable after Home Assistant restart
Direct answer: When MQTT entities become unavailable after Home Assistant restarts, the most common problem is not the entity itself. Home Assistant has reconnected to the broker, but it has not yet received the discovery or availability messages required to rebuild the entity and mark the device online. The safest fix is to verify the broker connection, confirm the device republishes discovery after Home Assistant’s birth message, and check whether the availability message is retained. Do not delete the MQTT integration or recreate every entity until you know which message is missing.

What this problem looks like
- MQTT entities worked normally before a Home Assistant restart but return as unavailable.
- The device is powered and still publishes data, yet its entities do not recover.
- Reloading MQTT temporarily restores some or all entities.
- Entities appear only after the physical device restarts.
- Manually republishing a discovery payload makes the entity return.
- The broker log shows Home Assistant reconnecting, but the expected discovery or online message is absent.
This guide applies to MQTT discovery and manually configured MQTT entities. It is especially relevant to devices or bridges that generate Home Assistant discovery payloads, including custom firmware, gateways, scripts, and home-built sensors.

Why MQTT entities can stay unavailable

MQTT is message based. Home Assistant cannot infer a device’s current state merely because the broker is reachable. Depending on the entity configuration, it may need several different messages:
- A discovery configuration message describing the entity.
- A state message containing the current value.
- An availability message such as online.
- A new message before an expire_after timer runs out.
Home Assistant’s MQTT documentation explains that, during startup, existing discovered devices and entities can remain unavailable until their discovery messages are received and processed. It recommends that devices subscribe to Home Assistant’s birth message and use it as a trigger to resend discovery. This matters when the original discovery configuration was not retained or when the publishing device started before Home Assistant.

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

Before changing anything
1. Record one affected entity ID and its device name.
2. Open the MQTT integration and download diagnostics if available.
3. Copy the entity’s discovery topic, state topic, and availability topic.
4. Note whether the failure happens after every restart or only intermittently.
5. Back up configuration files before editing YAML, templates, automations, or broker settings.
Avoid clearing retained topics broadly. Retained MQTT messages may be controlling discovery and availability for many devices. Deleting them without an exact topic list can remove working entities or revive stale configurations in confusing ways.

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

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

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

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

Step 2: Verify the discovery configuration is replayed

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

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

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

Step 3: Test the Home Assistant birth-message path

Home Assistant publishes a birth message when MQTT becomes available. A discovery publisher can subscribe to that status topic and resend its configurations when it sees the online payload. If entities appear only after restarting the device, this replay path is probably missing or broken.
1. Identify the birth topic and payload configured for Home Assistant.
2. Confirm the publishing device or bridge subscribes to that exact topic.
3. Check capitalization and spacing in the expected payload.
4. Restart only the MQTT integration or Home Assistant once while listening.
5. Verify that the publisher responds by sending its discovery configurations again.
Do not create an automation that repeatedly floods discovery messages. One response to the relevant birth event is enough.

Step 4: Inspect the availability topic and retained flag

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

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

Check for these failure patterns:
- The online message uses a different topic than the entity configuration.
- The device publishes Online while Home Assistant expects online.
- A retained offline message remains after the device reconnects.
- Multiple availability topics require all topics to be online when any was intended.
- The publisher reconnects without sending its current online state.
Step 5: Separate state retention from availability retention

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

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

Step 6: Check expire_after and message frequency

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

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

Step 7: Look for stale or duplicate discovery configurations

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

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

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

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

When to escalate

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

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

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

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

Special considerations for sleeping and battery-powered devices

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

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

Broker-session and permission checks

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

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

What to include when escalating

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

Evidence and testing disclosure

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

Sources
Last reviewed: September 8, 2026.

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

Decision guide: what should be retained?

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

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

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

Find your next troubleshooting path
Use the related guide that matches the next confirmed layer of the failure. Avoid changing unrelated systems at the same time.
September 8, 2026