From 20c7dcb1ddf6a70aaf75ff418499835c3e99228e Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@koston.org>
Date: Mon, 7 Sep 2026 00:26:44 +0200
Subject: [PATCH] [mdns] Guard LEAmDNS main loop calls against lwIP re-entrancy
 on ESP8266 (#18990)

---
 esphome/components/mdns/__init__.py      |  2 +
 esphome/components/mdns/mdns_esp8266.cpp | 51 +++++++++++++++++++++---
 2 files changed, 47 insertions(+), 6 deletions(-)

diff --git a/esphome/components/mdns/__init__.py b/esphome/components/mdns/__init__.py
index f039bb69f0..c8020104b3 100644
--- a/esphome/components/mdns/__init__.py
+++ b/esphome/components/mdns/__init__.py
@@ -192,6 +192,8 @@ async def to_code(config: ConfigType) -> None:
     if CORE.using_arduino:
         if CORE.is_esp8266:
             cg.add_library("ESP8266mDNS", None)
+            # No MDNS global in the build; mdns_esp8266.cpp owns a guarded MDNSResponder
+            cg.add_build_flag("-DNO_GLOBAL_MDNS")
         elif CORE.is_rp2:
             cg.add_library("LEAmDNS", None)
 
diff --git a/esphome/components/mdns/mdns_esp8266.cpp b/esphome/components/mdns/mdns_esp8266.cpp
index 1f0b3c9519..0e600d3bac 100644
--- a/esphome/components/mdns/mdns_esp8266.cpp
+++ b/esphome/components/mdns/mdns_esp8266.cpp
@@ -13,8 +13,47 @@
 
 namespace esphome::mdns {
 
+// Main-loop calls into LEAmDNS that send (update() and close(); begin(), addService() and
+// the scheduled restart never reach a send) can yield inside UdpContext::sendTimeout(); a
+// packet arriving then re-enters LEAmDNS from lwIP on the same UdpContext and both sides
+// free the same tx pbufs (#18760). Received packets stay queued during such a call and are
+// processed from the main loop afterwards.
+class GuardedMDNSResponder : public ::esp8266::MDNSImplementation::MDNSResponder {
+ public:
+  void update_guarded() { this->run_guarded_(&GuardedMDNSResponder::update); }
+  void close_guarded() { this->run_guarded_(&GuardedMDNSResponder::close); }
+
+ private:
+  void run_guarded_(bool (GuardedMDNSResponder::*fn)()) {
+    UdpContext *ctx = this->m_pUDPContext;
+    if (ctx == nullptr) {
+      (this->*fn)();
+      return;
+    }
+    // Set every time: a restart replaces the context together with its stock handler. Only
+    // begin() and the scheduled netif callback restart, never update() or close(), so the
+    // context cannot change underneath this call.
+    ctx->onRx([this]() {
+      if (!this->in_loop_call_) {
+        this->_callProcess();
+      }
+    });
+    this->in_loop_call_ = true;
+    (this->*fn)();
+    // close() releases the context; a yield in here queues further packets for this loop too
+    while (this->m_pUDPContext != nullptr && this->m_pUDPContext->next()) {
+      this->_parseMessage();
+    }
+    this->in_loop_call_ = false;
+  }
+
+  volatile bool in_loop_call_{false};
+};
+
+static GuardedMDNSResponder mdns_responder;  // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
+
 static void register_esp8266(MDNSComponent *, StaticVector<MDNSService, MDNS_SERVICE_COUNT> &services) {
-  MDNS.begin(App.get_name().c_str());
+  mdns_responder.begin(App.get_name().c_str());
 
   for (const auto &service : services) {
     // Strip the leading underscore from the proto and service_type. While it is
@@ -30,10 +69,10 @@ static void register_esp8266(MDNSComponent *, StaticVector<MDNSService, MDNS_SER
       service_type++;
     }
     uint16_t port = service.port.value();
-    MDNS.addService(FPSTR(service_type), FPSTR(proto), port);
+    mdns_responder.addService(FPSTR(service_type), FPSTR(proto), port);
     for (const auto &record : service.txt_records) {
-      MDNS.addServiceTxt(FPSTR(service_type), FPSTR(proto), FPSTR(MDNS_STR_ARG(record.key)),
-                         FPSTR(MDNS_STR_ARG(record.value)));
+      mdns_responder.addServiceTxt(FPSTR(service_type), FPSTR(proto), FPSTR(MDNS_STR_ARG(record.key)),
+                                   FPSTR(MDNS_STR_ARG(record.value)));
     }
   }
 }
@@ -52,7 +91,7 @@ void MDNSComponent::start_polling_window_() {
     if (wifi->is_roaming() || (!wifi->is_connected() && !wifi->is_ap_active()))
       return;
 #endif
-    MDNS.update();
+    mdns_responder.update_guarded();
   });
   this->set_timeout(MDNS_POLL_STOP_ID, MDNS_POLL_WINDOW_MS, [this]() { this->cancel_interval(MDNS_POLL_ID); });
 }
@@ -81,7 +120,7 @@ void MDNSComponent::on_ip_state(const network::IPAddresses &ips, const network::
 #endif
 
 void MDNSComponent::on_shutdown() {
-  MDNS.close();
+  mdns_responder.close_guarded();
   delay(10);
 }