From de0a202c4e9e12fc05f178efb4178995ecdd0d41 Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@koston.org>
Date: Mon, 1 Jun 2026 04:42:00 -0500
Subject: [PATCH] Explain why a Switchbot device could not be found (#172581)

---
 homeassistant/components/switchbot/__init__.py | 18 +++++++++++++++++-
 .../components/switchbot/strings.json          |  2 +-
 2 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/homeassistant/components/switchbot/__init__.py b/homeassistant/components/switchbot/__init__.py
index 45f3cbdcf940..9a2d8f4a47bc 100644
--- a/homeassistant/components/switchbot/__init__.py
+++ b/homeassistant/components/switchbot/__init__.py
@@ -6,6 +6,7 @@ from typing import Any
 import switchbot
 
 from homeassistant.components import bluetooth
+from homeassistant.components.bluetooth import BluetoothReachabilityIntent
 from homeassistant.components.sensor import ConfigType
 from homeassistant.config_entries import ConfigEntry
 from homeassistant.const import (
@@ -310,6 +311,11 @@ async def async_setup_entry(hass: HomeAssistant, entry: SwitchbotConfigEntry) ->
             translation_placeholders={
                 "sensor_type": entry.data[CONF_SENSOR_TYPE],
                 "address": entry.data[CONF_ADDRESS],
+                "reason": bluetooth.async_address_reachability_diagnostics(
+                    hass,
+                    entry.data[CONF_ADDRESS].upper(),
+                    BluetoothReachabilityIntent.CONNECTION,
+                ),
             },
         )
 
@@ -331,7 +337,17 @@ async def async_setup_entry(hass: HomeAssistant, entry: SwitchbotConfigEntry) ->
         raise ConfigEntryNotReady(
             translation_domain=DOMAIN,
             translation_key="device_not_found_error",
-            translation_placeholders={"sensor_type": sensor_type, "address": address},
+            translation_placeholders={
+                "sensor_type": sensor_type,
+                "address": address,
+                "reason": bluetooth.async_address_reachability_diagnostics(
+                    hass,
+                    address.upper(),
+                    BluetoothReachabilityIntent.CONNECTION
+                    if connectable
+                    else BluetoothReachabilityIntent.PASSIVE_ADVERTISEMENT,
+                ),
+            },
         )
 
     cls = CLASS_BY_DEVICE.get(sensor_type, switchbot.SwitchbotDevice)
diff --git a/homeassistant/components/switchbot/strings.json b/homeassistant/components/switchbot/strings.json
index 5ddd6d561d77..076be9c30dbd 100644
--- a/homeassistant/components/switchbot/strings.json
+++ b/homeassistant/components/switchbot/strings.json
@@ -384,7 +384,7 @@
       "message": "The device ID {device_id} does not belong to SwitchBot integration."
     },
     "device_not_found_error": {
-      "message": "Could not find Switchbot {sensor_type} with address {address}"
+      "message": "Could not find Switchbot {sensor_type} with address {address}: {reason}"
     },
     "device_without_config_entry": {
       "message": "The device ID {device_id} is not associated with a config entry."