From ba1ad765ea6bb0664acd74cf64903691853a0d14 Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@home-assistant.io>
Date: Sat, 22 Aug 2026 21:41:50 -0500
Subject: [PATCH] Name the probe failure cause in the tool-version warning

---
 esphome/framework_helpers.py | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/esphome/framework_helpers.py b/esphome/framework_helpers.py
index 7911acb111..b473354f82 100644
--- a/esphome/framework_helpers.py
+++ b/esphome/framework_helpers.py
@@ -215,8 +215,10 @@ def tool_version_runs(binary: str, warning: str) -> bool:
             # Repo-wide convention (posix_spawn fast path)
             close_fds=False,
         )
-    except (OSError, subprocess.SubprocessError):
-        _LOGGER.warning(warning, binary)
+    except (OSError, subprocess.SubprocessError) as err:
+        # The cause (permission denied, missing DLL, timeout) is the one
+        # detail the user needs to fix it
+        _LOGGER.warning("%s (%s)", warning % binary, err)
         return False
     return True