Explain why a Snooz device could not be found (#172780)

homeassistant/components/snooz/__init__.py

@@ -4,12 +4,16 @@ import logging
 
 from pysnooz.device import SnoozDevice
 
-from homeassistant.components.bluetooth import async_ble_device_from_address
+from homeassistant.components.bluetooth import (
+    BluetoothReachabilityIntent,
+    async_address_reachability_diagnostics,
+    async_ble_device_from_address,
+)
 from homeassistant.const import CONF_ADDRESS, CONF_TOKEN
 from homeassistant.core import HomeAssistant
 from homeassistant.exceptions import ConfigEntryNotReady
 
-from .const import PLATFORMS
+from .const import DOMAIN, PLATFORMS
 from .models import SnoozConfigEntry, SnoozConfigurationData
 
 
@@ -23,7 +27,16 @@ async def async_setup_entry(hass: HomeAssistant, entry: SnoozConfigEntry) -> boo
 
     if not (ble_device := async_ble_device_from_address(hass, address)):
         raise ConfigEntryNotReady(
-            f"Could not find Snooz with address {address}. Try power cycling the device"
+            translation_domain=DOMAIN,
+            translation_key="device_not_found",
+            translation_placeholders={
+                "address": address,
+                "reason": async_address_reachability_diagnostics(
+                    hass,
+                    address.upper(),
+                    BluetoothReachabilityIntent.CONNECTION,
+                ),
+            },
         )
 
     device = SnoozDevice(ble_device, token)

homeassistant/components/snooz/strings.json

@@ -24,6 +24,11 @@
       }
     }
   },
+  "exceptions": {
+    "device_not_found": {
+      "message": "Could not find Snooz with address {address}: {reason}"
+    }
+  },
   "services": {
     "transition_off": {
       "description": "Transitions the volume level to the lowest setting over a specified duration, then powers off the device.",

tests/components/snooz/test_init.py

@@ -1,8 +1,49 @@
 """Test Snooz configuration."""
 
+from unittest.mock import patch
+
+import pytest
+
+from homeassistant.components.snooz.const import DOMAIN
+from homeassistant.config_entries import ConfigEntryState
+from homeassistant.const import CONF_ADDRESS, CONF_TOKEN
 from homeassistant.core import HomeAssistant
 
-from . import SnoozFixture
+from . import TEST_ADDRESS, TEST_PAIRING_TOKEN, SnoozFixture
+
+from tests.common import MockConfigEntry
+
+
+async def test_setup_retries_when_device_not_found(
+    hass: HomeAssistant,
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """Test setup is retried with a diagnostic reason when the device is missing."""
+    entry = MockConfigEntry(
+        domain=DOMAIN,
+        unique_id=TEST_ADDRESS,
+        data={CONF_ADDRESS: TEST_ADDRESS, CONF_TOKEN: TEST_PAIRING_TOKEN},
+    )
+    entry.add_to_hass(hass)
+
+    with (
+        patch(
+            "homeassistant.components.snooz.async_ble_device_from_address",
+            return_value=None,
+        ),
+        patch(
+            "homeassistant.components.snooz.async_address_reachability_diagnostics",
+            return_value="mock reachability reason",
+        ),
+    ):
+        await hass.config_entries.async_setup(entry.entry_id)
+        await hass.async_block_till_done()
+
+    assert entry.state is ConfigEntryState.SETUP_RETRY
+    assert (
+        f"Could not find Snooz with address {TEST_ADDRESS}: mock reachability reason"
+        in caplog.text
+    )
 
 
 async def test_removing_entry_cleans_up_connections(