[core] Fix KeyError: 'esp32' on upload when validated-config cache is used (#16457)

esphome/storage_json.py

@@ -273,10 +273,21 @@ class StorageJSON:
         """
         CORE.name = self.name
         CORE.build_path = self.build_path
+        target_platform = self.core_platform or self.target_platform.lower()
         CORE.data[KEY_CORE] = {
-            KEY_TARGET_PLATFORM: self.core_platform or self.target_platform.lower(),
+            KEY_TARGET_PLATFORM: target_platform,
             KEY_TARGET_FRAMEWORK: self.framework,
         }
+        # The compile pipeline populates CORE.data[KEY_ESP32] when esp32's
+        # validator runs; on the cache fast path that validator is skipped,
+        # so populate the variant upload_using_esptool reads via
+        # esp32.get_esp32_variant(). target_platform on disk is the variant
+        # (e.g. "ESP32S3"); core_platform is the family (e.g. "esp32").
+        if target_platform == const.PLATFORM_ESP32:
+            from esphome.components.esp32.const import KEY_ESP32
+            from esphome.const import KEY_VARIANT
+
+            CORE.data[KEY_ESP32] = {KEY_VARIANT: self.target_platform}
 
     def __eq__(self, o) -> bool:
         return isinstance(o, StorageJSON) and self.as_dict() == o.as_dict()

tests/unit_tests/test_compiled_config.py

@@ -22,6 +22,7 @@ from esphome.const import (
     KEY_CORE,
     KEY_TARGET_FRAMEWORK,
     KEY_TARGET_PLATFORM,
+    KEY_VARIANT,
 )
 from esphome.core import CORE
 
@@ -47,7 +48,12 @@ wifi:
 """
 
 
-def _write_storage(storage_path: Path) -> None:
+def _write_storage(
+    storage_path: Path,
+    *,
+    esp_platform: str = "ESP32",
+    core_platform: str | None = "esp32",
+) -> None:
     """Write a vanilla StorageJSON sidecar for the cache tests."""
     storage_path.parent.mkdir(parents=True, exist_ok=True)
     data = {
@@ -59,14 +65,14 @@ def _write_storage(storage_path: Path) -> None:
         "src_version": 1,
         "address": "192.168.1.42",
         "web_port": None,
-        "esp_platform": "ESP32",
+        "esp_platform": esp_platform,
         "build_path": "/build/lite_test",
         "firmware_bin_path": "/build/lite_test/firmware.bin",
         "loaded_integrations": ["api", "logger", "ota", "wifi"],
         "loaded_platforms": [],
         "no_mdns": False,
         "framework": "arduino",
-        "core_platform": "esp32",
+        "core_platform": core_platform,
     }
     storage_path.write_text(json.dumps(data))
 
@@ -123,6 +129,50 @@ def test_load_compiled_config_happy_path(fresh_cache_files: Path) -> None:
     assert CORE.build_path == Path("/build/lite_test")
     assert CORE.data[KEY_CORE][KEY_TARGET_PLATFORM] == "esp32"
     assert CORE.data[KEY_CORE][KEY_TARGET_FRAMEWORK] == "arduino"
+    # upload_using_esptool reads get_esp32_variant() off CORE.data[KEY_ESP32].
+    from esphome.components.esp32.const import KEY_ESP32
+
+    assert CORE.data[KEY_ESP32][KEY_VARIANT] == "ESP32"
+
+
+def test_load_compiled_config_populates_esp32_variant(tmp_path: Path) -> None:
+    """ESP32 variants survive the cache fast path so esptool gets the right --chip."""
+    from esphome.components.esp32.const import KEY_ESP32
+
+    yaml_path = tmp_path / "lite_test.yaml"
+    yaml_path.write_text("esphome:\n  name: lite_test\n")
+    CORE.config_path = yaml_path
+
+    storage_dir = tmp_path / ".esphome" / "storage"
+    _write_storage(storage_dir / "lite_test.yaml.json", esp_platform="ESP32S3")
+    cache = _write_cache(storage_dir / "lite_test.yaml.validated.yaml")
+    _set_cache_mtime(cache, yaml_path, offset=5)
+
+    assert load_compiled_config(yaml_path) is not None
+    assert CORE.data[KEY_ESP32][KEY_VARIANT] == "ESP32S3"
+
+
+def test_load_compiled_config_skips_esp32_block_for_other_platforms(
+    tmp_path: Path,
+) -> None:
+    """Non-esp32 targets shouldn't fabricate an esp32 data block."""
+    from esphome.components.esp32.const import KEY_ESP32
+
+    yaml_path = tmp_path / "lite_test.yaml"
+    yaml_path.write_text("esphome:\n  name: lite_test\n")
+    CORE.config_path = yaml_path
+
+    storage_dir = tmp_path / ".esphome" / "storage"
+    _write_storage(
+        storage_dir / "lite_test.yaml.json",
+        esp_platform="ESP8266",
+        core_platform="esp8266",
+    )
+    cache = _write_cache(storage_dir / "lite_test.yaml.validated.yaml")
+    _set_cache_mtime(cache, yaml_path, offset=5)
+
+    assert load_compiled_config(yaml_path) is not None
+    assert KEY_ESP32 not in CORE.data
 
 
 @pytest.mark.parametrize(