Direct answer: When an ESPHome Bluetooth proxy becomes unavailable, confirm the proxy itself is online through the ESPHome native API before troubleshooting Bluetooth devices. Then inspect Wi-Fi stability, API encryption, proxy mode, coverage, and connection-slot limits. A working proxy and a discoverable Bluetooth device are two different checkpoints.
Safety first: Preserve a current Home Assistant backup and record entity IDs, device names, IP addresses, integration settings, and the exact error before changing anything. Never expose tokens, passwords, encryption keys, webhook URLs, or unredacted diagnostics. Do not factory-reset equipment, delete an integration, or open mains-powered hardware as a first troubleshooting step.
Confirm the failure boundary
Separate proxy availability in Home Assistant from Bluetooth discovery and from active connections. If the proxy device is unavailable, fix its ESPHome API path first. If the proxy is online but a sensor is missing, investigate advertisements, distance, interference, and integration support.
Determine whether the problem affects one device, one integration, or every device using the same network path. A single-device failure usually points to power, addressing, credentials, firmware, or device-specific settings. Several failures beginning together point toward Home Assistant, DNS, routing, firewall policy, an upstream service, or a recent update.
Quick diagnostic table
| Observation | Likely layer | Next safe check |
|---|---|---|
| Proxy device itself unavailable | ESPHome API or Wi-Fi | Check address, power, logs, and encryption key |
| Advertisements visible but control fails | Active connection path | Check active proxy mode and connection slots |
| Only distant devices fail | RF coverage | Move or add a proxy after a temporary range test |
| All Bluetooth devices fail | Home Assistant Bluetooth layer | Review adapters, proxies, and integration logs |
Step 1: preserve evidence
Write down when the failure began, the last known working version, recent updates, router or VLAN changes, and the full error text. Open Settings → System → Logs and the integration entry under Settings → Devices & services. Download diagnostics when available. Evidence collected before a restart is often more valuable than evidence collected afterward.
Step 2: verify the basic path
Check the proxy in ESPHome Device Builder, its DHCP lease, signal level, uptime, and logs. Confirm Home Assistant can reach the native API address and that the encryption key matches. Unstable power can create repeated short connections that resemble weak Bluetooth coverage.
Use the least invasive test that separates network reachability from application authentication. A successful ping proves only that an address responds; it does not prove that the required port, protocol, credentials, certificate, or API is working. Likewise, a vendor app working through the cloud does not prove that local communication from Home Assistant is allowed.
Step 3: check configuration and credentials
Confirm the ESPHome configuration includes the current Bluetooth proxy component and native API. Passive observation and active connections have different requirements. Validate the configuration with the current ESPHome release before compiling, and preserve the working YAML and encryption key.
Prefer the integration’s Reconfigure or Reauthenticate flow over deleting it. Deletion can remove entity-registry relationships and break dashboards or automations. If credentials changed, update only the affected entry and verify one harmless entity before touching anything else.
Step 4: inspect networking without weakening security
The proxy transports Bluetooth data to Home Assistant over IP. Wi-Fi client isolation, VLAN rules, DNS, mDNS, or a changed DHCP address can break that transport. Fix the precise Home Assistant-to-proxy path; do not expose port 6053 publicly.
If Home Assistant and the device are on different VLANs, test temporarily on the same trusted network. If that works, restore the intended layout and create the narrowest required rule. Do not expose local APIs to the public internet, disable the firewall globally, or create an unrestricted route from an untrusted IoT network to the main LAN.
Step 5: read logs and reproduce once
Correlate ESPHome boot messages, Wi-Fi reconnects, API client connections, Bluetooth scan messages, and memory or watchdog warnings. Repeated boots point toward power or firmware. A stable API connection with no advertisements points toward RF range, device advertising, or hardware.
Enable debug logging only long enough to reproduce the failure once. Then disable it and download the log. Look for the first meaningful error, not every secondary warning that follows. Match timestamps between Home Assistant, the add-on or bridge, the router, and the vendor service when applicable.
Step 6: make one reversible change
Reconfigure the correct address or encryption key, stabilize power, or perform a short same-room range test. Add another proxy only after proving coverage is the problem. Update firmware one proxy at a time so a bad build does not remove all Bluetooth coverage.
After each change, wait through several normal update intervals. Changing DNS, credentials, firmware, firewall rules, and device configuration at the same time may produce a temporary success without revealing the cause. Record the old value and the test result so you can roll back cleanly.
How to verify the repair
- The proxy remains available through several Wi-Fi and API intervals.
- Expected advertisements appear with stable signal strength.
- A supported active-connection device accepts one harmless command.
- Home Assistant reconnects to the proxy after a controlled restart.
A repair is not verified by a green icon alone. Confirm fresh state updates, send one low-risk command, verify the physical response, and make sure the returned state matches. Watch long enough to cover normal polling, sleep, or reconnect behavior.
Rollback and escalation
Keep the previous ESPHome YAML and firmware available. If a new build causes instability, restore the known-good configuration using a supported local or USB recovery method rather than repeatedly attempting over-the-air updates.
If escalation is necessary, provide the exact model, firmware, Home Assistant version, integration version, network layout, redacted diagnostics, timestamps, and the checks already completed. A concise evidence package gets better help than a broad statement that the integration is broken.
Prevent recurrence
- Use reliable power supplies and cables for proxies.
- Create DHCP reservations or dependable local name resolution.
- Place multiple proxies with overlapping—but not excessive—coverage.
- Update and test one proxy before rolling changes to the rest.
Related Troubliq guides
- Smart-Home Diagnostic Decision Tree
- Why Is My Smart-Home Device Unavailable?
- Browse all troubleshooting guides
Sources and review record
Last reviewed: September 21, 2026. Testing disclosure: This guide follows current official documentation and established diagnostic practice; exact menus can vary by release, installation type, and device firmware.
Advanced isolation checklist
When the basic checks do not identify the cause, build a controlled comparison. Test one known-good device, account, or client through the same path, and test the affected device through a simpler path when safe. Compare timestamps, addresses, authentication method, firmware, and permissions. The purpose is to change one boundary at a time, not to keep trying random fixes.
Review release notes for Home Assistant, the integration, add-on, device firmware, and any reverse proxy or network service updated near the failure. Confirm a reported workaround applies to the same product and version before using it. Prefer an official repair or documented reconfiguration over unsupported downgrades.
What not to do
- Do not factory-reset multiple devices together.
- Do not delete a working integration merely to clear a warning.
- Do not expose local services or dashboards directly to the internet.
- Do not post secrets or unredacted diagnostic files.
- Do not assume a successful mobile-app test proves the Home Assistant path works.
Detailed evidence checklist for Home Assistant Bluetooth proxy unavailable
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
- Correct time, power, cabling, or an obviously stale address.
- Reload only the affected integration when documentation supports it.
- Use Reconfigure or Reauthenticate without deleting the entry.
- Restart only the affected device or add-on during a safe window.
- Restart Home Assistant when several components share the symptom or a change requires it.
- Update software after reading release notes and preserving rollback.
- 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.