From 8d48785e4fbd2253298fdea0eec25fef19e38ef1 Mon Sep 17 00:00:00 2001
From: Erik Montnemery <erik@montnemery.com>
Date: Thu, 3 Sep 2026 12:04:21 +0200
Subject: [PATCH] Deprecate passing a target to
 homeassistant.reload_config_entry (#181142)

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
---
 homeassistant/components/homeassistant/__init__.py |  6 ++++++
 .../components/homeassistant/services.yaml         |  5 +++--
 .../components/homeassistant/strings.json          |  4 ++--
 tests/components/homeassistant/test_init.py        | 14 ++++++++++++--
 4 files changed, 23 insertions(+), 6 deletions(-)

diff --git a/homeassistant/components/homeassistant/__init__.py b/homeassistant/components/homeassistant/__init__.py
index f806cd63c5e3..5e66be54232e 100644
--- a/homeassistant/components/homeassistant/__init__.py
+++ b/homeassistant/components/homeassistant/__init__.py
@@ -343,6 +343,12 @@ async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool:  # noqa:
         reload_entries: set[str] = set()
         if ATTR_ENTRY_ID in call.data:
             reload_entries.add(call.data[ATTR_ENTRY_ID])
+        if TargetSelection(call.data).has_any_target:
+            _LOGGER.warning(
+                "Reloading a config entry by target is deprecated and will stop "
+                "working in Home Assistant 2027.4, please specify the config entry "
+                "to reload in the 'entry_id' parameter instead"
+            )
         reload_entries.update(await async_extract_config_entry_ids(call))
         if not reload_entries:
             raise ValueError("There were no matching config entries to reload")
diff --git a/homeassistant/components/homeassistant/services.yaml b/homeassistant/components/homeassistant/services.yaml
index edcc87b2f35f..d3b3cdbe40b5 100644
--- a/homeassistant/components/homeassistant/services.yaml
+++ b/homeassistant/components/homeassistant/services.yaml
@@ -49,10 +49,11 @@ update_entity:
 
 reload_custom_templates:
 reload_config_entry:
-  target:
+  # Target is intentionally hidden from the UI to steer users towards selecting
+  # the config entry to reload. It is still accepted by the service schema.
   fields:
     entry_id:
-      required: false
+      required: true
       selector:
         config_entry:
 
diff --git a/homeassistant/components/homeassistant/strings.json b/homeassistant/components/homeassistant/strings.json
index 39470f45edd8..a65993f9b09f 100644
--- a/homeassistant/components/homeassistant/strings.json
+++ b/homeassistant/components/homeassistant/strings.json
@@ -262,10 +262,10 @@
       "name": "Reload all Home Assistant configuration"
     },
     "reload_config_entry": {
-      "description": "Reloads any explicitly provided config entry ID and any config entries referenced by entities or devices in the target. If both are provided, the union of those config entries is reloaded.",
+      "description": "Reloads the config entry of the provided config entry ID.",
       "fields": {
         "entry_id": {
-          "description": "Optional configuration entry ID to reload.",
+          "description": "The configuration entry to reload.",
           "name": "Config entry ID"
         }
       },
diff --git a/tests/components/homeassistant/test_init.py b/tests/components/homeassistant/test_init.py
index b23939cb4030..c2e612dfd784 100644
--- a/tests/components/homeassistant/test_init.py
+++ b/tests/components/homeassistant/test_init.py
@@ -368,7 +368,9 @@ async def test_not_allowing_recursion(
 
 
 async def test_reload_config_entry_by_entity_id(
-    hass: HomeAssistant, entity_registry: er.EntityRegistry
+    hass: HomeAssistant,
+    entity_registry: er.EntityRegistry,
+    caplog: pytest.LogCaptureFixture,
 ) -> None:
     """Test being able to reload a config entry by entity_id."""
     await async_setup_component(hass, DOMAIN, {})
@@ -398,6 +400,11 @@ async def test_reload_config_entry_by_entity_id(
         entry1.entry_id,
         entry2.entry_id,
     }
+    assert (
+        "Reloading a config entry by target is deprecated and will stop working in "
+        "Home Assistant 2027.4, please specify the config entry to reload in the "
+        "'entry_id' parameter instead"
+    ) in caplog.text
 
     with pytest.raises(ValueError):
         await hass.services.async_call(
@@ -408,7 +415,9 @@ async def test_reload_config_entry_by_entity_id(
         )
 
 
-async def test_reload_config_entry_by_entry_id(hass: HomeAssistant) -> None:
+async def test_reload_config_entry_by_entry_id(
+    hass: HomeAssistant, caplog: pytest.LogCaptureFixture
+) -> None:
     """Test being able to reload a config entry by config entry id."""
     await async_setup_component(hass, DOMAIN, {})
 
@@ -425,6 +434,7 @@ async def test_reload_config_entry_by_entry_id(hass: HomeAssistant) -> None:
 
     assert len(mock_reload.mock_calls) == 1
     assert mock_reload.mock_calls[0][1][0] == "8955375327824e14ba89e4b29cc3ec9a"
+    assert "Reloading a config entry by target is deprecated" not in caplog.text
 
 
 @pytest.mark.parametrize(