From 14b9915914264b013c573fae6b4b7f750dde465a Mon Sep 17 00:00:00 2001
From: Jan Bouwhuis <jbouwh@users.noreply.github.com>
Date: Mon, 30 Mar 2026 16:16:31 +0200
Subject: [PATCH] Add repair flow when MQTT YAML config is present but the
 broker is not set up correctly (#165090)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Joost Lekkerkerker <joostlek@outlook.com>
---
 homeassistant/components/mqtt/__init__.py  | 13 +++++++
 homeassistant/components/mqtt/strings.json |  4 ++
 tests/components/mqtt/test_init.py         | 45 +++++++++++++++++++++-
 3 files changed, 61 insertions(+), 1 deletion(-)

diff --git a/homeassistant/components/mqtt/__init__.py b/homeassistant/components/mqtt/__init__.py
index d6f14828050..fb3d84041be 100644
--- a/homeassistant/components/mqtt/__init__.py
+++ b/homeassistant/components/mqtt/__init__.py
@@ -311,6 +311,19 @@ def _platforms_in_use(hass: HomeAssistant, entry: ConfigEntry) -> set[str | Plat
 async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool:
     """Set up the actions and websocket API for the MQTT component."""
 
+    if config.get(DOMAIN) and not mqtt_config_entry_enabled(hass):
+        issue_registry = ir.async_get(hass)
+        issue_registry.async_get_or_create(
+            DOMAIN,
+            "yaml_setup_without_active_setup",
+            is_fixable=False,
+            is_persistent=False,
+            severity=ir.IssueSeverity.WARNING,
+            learn_more_url="https://www.home-assistant.io/integrations/mqtt/"
+            "#configuration",
+            translation_key="yaml_setup_without_active_setup",
+        )
+
     websocket_api.async_register_command(hass, websocket_subscribe)
     websocket_api.async_register_command(hass, websocket_mqtt_info)
 
diff --git a/homeassistant/components/mqtt/strings.json b/homeassistant/components/mqtt/strings.json
index a50c39aa5ea..4b09d3558b3 100644
--- a/homeassistant/components/mqtt/strings.json
+++ b/homeassistant/components/mqtt/strings.json
@@ -1141,6 +1141,10 @@
         }
       },
       "title": "MQTT device \"{name}\" subentry migration to YAML"
+    },
+    "yaml_setup_without_active_setup": {
+      "description": "Home Assistant detected manually configured MQTT items, but these items cannot be loaded because MQTT is not set up correctly. Make sure the MQTT broker is set up correctly, or remove the MQTT configuration from your `configuration.yaml` file and restart Home Assistant to fix this issue.",
+      "title": "MQTT is not set up correctly"
     }
   },
   "options": {
diff --git a/tests/components/mqtt/test_init.py b/tests/components/mqtt/test_init.py
index a9896ee318c..93ff1d4a955 100644
--- a/tests/components/mqtt/test_init.py
+++ b/tests/components/mqtt/test_init.py
@@ -33,7 +33,12 @@ from homeassistant.const import (
 )
 from homeassistant.core import HomeAssistant, callback
 from homeassistant.exceptions import HomeAssistantError, ServiceValidationError
-from homeassistant.helpers import device_registry as dr, entity_registry as er, template
+from homeassistant.helpers import (
+    device_registry as dr,
+    entity_registry as er,
+    issue_registry as ir,
+    template,
+)
 from homeassistant.helpers.entity import Entity
 from homeassistant.helpers.entity_platform import async_get_platforms
 from homeassistant.helpers.typing import ConfigType
@@ -2304,3 +2309,41 @@ async def test_multi_platform_discovery(
 async def test_mqtt_integration_level_imports(attr: str) -> None:
     """Test mqtt integration level public published imports are available."""
     assert hasattr(mqtt, attr)
+
+
+@pytest.mark.usefixtures("mqtt_client_mock")
+@pytest.mark.parametrize(
+    "hass_config", [{mqtt.DOMAIN: {"sensor": {"state_topic": "test-topic"}}}]
+)
+async def test_yaml_config_without_entry(
+    hass: HomeAssistant, hass_config: ConfigType, issue_registry: ir.IssueRegistry
+) -> None:
+    """Test a repair issue is created for YAML setup without an active config entry."""
+    await async_setup_component(hass, mqtt.DOMAIN, hass_config)
+    issue = issue_registry.async_get_issue(
+        mqtt.DOMAIN, "yaml_setup_without_active_setup"
+    )
+    assert issue is not None
+    assert (
+        issue.learn_more_url == "https://www.home-assistant.io/integrations/mqtt/"
+        "#configuration"
+    )
+
+
+@pytest.mark.parametrize(
+    "hass_config", [{mqtt.DOMAIN: {"sensor": {"state_topic": "test-topic"}}}]
+)
+async def test_yaml_config_with_active_mqtt_config_entry(
+    hass: HomeAssistant,
+    hass_config: ConfigType,
+    mqtt_mock_entry: MqttMockHAClientGenerator,
+    issue_registry: ir.IssueRegistry,
+) -> None:
+    """Test no repair issue is created for YAML setup with an active config entry."""
+    await mqtt_mock_entry()
+    issue = issue_registry.async_get_issue(
+        mqtt.DOMAIN, "yaml_setup_without_active_setup"
+    )
+    state = hass.states.get("sensor.mqtt_sensor")
+    assert state is not None
+    assert issue is None