Deprecate http.server_host option and raise issue if used (home-assistant#155849)

Co-authored-by: Robert Resch <[email protected]>
Co-authored-by: Abílio Costa <[email protected]>

Author: 3 people

homeassistant/components/http/__init__.py

@@ -108,6 +108,7 @@
 
 HTTP_SCHEMA: Final = vol.All(
     cv.deprecated(CONF_BASE_URL),
+    cv.deprecated(CONF_SERVER_HOST),  # Deprecated in HA Core 2025.12
     vol.Schema(
         {
             vol.Optional(CONF_SERVER_HOST): vol.All(
@@ -208,14 +209,21 @@ async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool:
     if conf is None:
         conf = cast(ConfData, HTTP_SCHEMA({}))
 
-    if CONF_SERVER_HOST in conf and is_hassio(hass):
+    if CONF_SERVER_HOST in conf:
+        if is_hassio(hass):
+            issue_id = "server_host_deprecated_hassio"
+            severity = ir.IssueSeverity.ERROR
+        else:
+            issue_id = "server_host_deprecated"
+            severity = ir.IssueSeverity.WARNING
         ir.async_create_issue(
             hass,
             DOMAIN,
-            "server_host_may_break_hassio",
+            issue_id,
+            breaks_in_ha_version="2026.6.0",
             is_fixable=False,
-            severity=ir.IssueSeverity.ERROR,
-            translation_key="server_host_may_break_hassio",
+            severity=severity,
+            translation_key=issue_id,
         )
 
     server_host = conf.get(CONF_SERVER_HOST, _DEFAULT_BIND)

homeassistant/components/http/strings.json

@@ -1,7 +1,11 @@
 {
   "issues": {
-    "server_host_may_break_hassio": {
-      "description": "The `server_host` configuration option in the HTTP integration is prone to break the communication between Home Assistant Core and Supervisor, and will be removed in a future release.\n\nIf you are using this option to bind Home Assistant to specific network interfaces, please remove it from your configuration. Home Assistant will automatically bind to all available interfaces by default.\n\nIf you have specific networking requirements, consider using firewall rules or other network configuration to control access to Home Assistant.",
+    "server_host_deprecated": {
+      "description": "The `server_host` configuration option in the HTTP integration is deprecated and will be removed.\n\nIf you are using this option to bind Home Assistant to specific network interfaces, please remove it from your configuration. Home Assistant will automatically bind to all available interfaces by default.\n\nIf you have specific networking requirements, consider using firewall rules or other network configuration to control access to Home Assistant.",
+      "title": "The `server_host` HTTP configuration option is deprecated"
+    },
+    "server_host_deprecated_hassio": {
+      "description": "The deprecated `server_host` configuration option in the HTTP integration is prone to break the communication between Home Assistant Core and Supervisor, and will be removed.\n\nIf you are using this option to bind Home Assistant to specific network interfaces, please remove it from your configuration. Home Assistant will automatically bind to all available interfaces by default.\n\nIf you have specific networking requirements, consider using firewall rules or other network configuration to control access to Home Assistant.",
       "title": "The `server_host` HTTP configuration may break Home Assistant Core - Supervisor communication"
     },
     "ssl_configured_without_configured_urls": {

tests/components/http/test_init.py

@@ -683,19 +683,27 @@ async def test_ssl_issue_urls_configured(
         "hassio",
         "http_config",
         "expected_serverhost",
+        "expected_warning_count",
         "expected_issues",
     ),
     [
-        (False, {}, ["0.0.0.0", "::"], set()),
-        (False, {"server_host": "0.0.0.0"}, ["0.0.0.0"], set()),
-        (True, {}, ["0.0.0.0", "::"], set()),
+        (False, {}, ["0.0.0.0", "::"], 0, set()),
+        (
+            False,
+            {"server_host": "0.0.0.0"},
+            ["0.0.0.0"],
+            1,
+            {("http", "server_host_deprecated")},
+        ),
+        (True, {}, ["0.0.0.0", "::"], 0, set()),
         (
             True,
             {"server_host": "0.0.0.0"},
             [
                 "0.0.0.0",
             ],
-            {("http", "server_host_may_break_hassio")},
+            1,
+            {("http", "server_host_deprecated_hassio")},
         ),
     ],
 )
@@ -705,7 +713,9 @@ async def test_server_host(
     issue_registry: ir.IssueRegistry,
     http_config: dict,
     expected_serverhost: list,
+    expected_warning_count: int,
     expected_issues: set[tuple[str, str]],
+    caplog: pytest.LogCaptureFixture,
 ) -> None:
     """Test server_host behavior."""
     mock_server = Mock()
@@ -733,4 +743,11 @@ async def test_server_host(
         reuse_port=None,
     )
 
+    assert (
+        caplog.text.count(
+            "The 'server_host' option is deprecated, please remove it from your configuration"
+        )
+        == expected_warning_count
+    )
+
     assert set(issue_registry.issues) == expected_issues