From e3d29e9fff5c866372e679cdeeaad19b225d9dc6 Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@home-assistant.io>
Date: Fri, 21 Aug 2026 15:18:54 -0500
Subject: [PATCH] Name a non-list registry system field instead of a TypeError

file["system"] normalized None and str but let an int or dict fall
through to the in test, where an int raises TypeError and a dict
becomes a key test; both now raise the same Unexpected-response error
as the other shape guards.
---
 esphome/platformio/registry.py               |  6 ++++++
 tests/unit_tests/test_platformio_registry.py | 10 ++++++++++
 2 files changed, 16 insertions(+)

diff --git a/esphome/platformio/registry.py b/esphome/platformio/registry.py
index 7ffd7f8bb1..09a66e0cf9 100644
--- a/esphome/platformio/registry.py
+++ b/esphome/platformio/registry.py
@@ -109,6 +109,12 @@ def registry_download(package: str, version: str) -> tuple[str, str, int | None]
                 systems = ["*"]
             elif isinstance(systems, str):
                 systems = [systems]
+            elif not isinstance(systems, list):
+                # An int would make ``in`` a TypeError and a dict a key test
+                raise EsphomeError(
+                    f"Unexpected package registry response for {package}: "
+                    f"{str(file)[:200]}"
+                )
             if "*" in systems or systype in systems:
                 sha256 = (file.get("checksum") or {}).get("sha256")
                 if not sha256:
diff --git a/tests/unit_tests/test_platformio_registry.py b/tests/unit_tests/test_platformio_registry.py
index 6d513a78d1..4f83048aab 100644
--- a/tests/unit_tests/test_platformio_registry.py
+++ b/tests/unit_tests/test_platformio_registry.py
@@ -442,3 +442,13 @@ def test_registry_download_non_dict_payload_is_named() -> None:
         pytest.raises(EsphomeError, match="Unexpected package registry response"),
     ):
         registry.registry_download("pkg", "1.0.0")
+
+
+def test_registry_download_non_list_system_is_named() -> None:
+    """A system field that is neither missing, str, nor list is an
+    unexpected payload, not a TypeError from the ``in`` test."""
+    with (
+        _registry_response([{"system": 5, "checksum": {"sha256": "abc"}, "size": 1}]),
+        pytest.raises(EsphomeError, match="Unexpected package registry response"),
+    ):
+        registry.registry_download("pkg", "1.0.0")