The Bug Wasn't in My Code
- ceceliazhen
- Jun 24
- 2 min read
I spent most of the weekend convinced that I had broken my ESP32 project.
The goal seemed simple enough: add MQTT communication so I could remotely control my ESP32-S3 multimedia player from my computer. I already had a TFT display showing images, an I2S speaker playing melodies, Wi-Fi connectivity, and a web interface. MQTT was supposed to be the next small upgrade.
Instead, it turned into a debugging adventure.
The first symptom was confusing. My ESP32 kept reporting:
"Connecting MQTT... failed, rc=-2"
Naturally, I assumed I had made a coding mistake. I reviewed my callback functions, checked my MQTT topics, verified my broker address, rebuilt the project multiple times, and even questioned whether my speaker code was interfering with the network stack.
Then things became stranger.
My web interface stopped responding. The music wouldn't play. MQTTX kept reconnecting. Every fix seemed to create a new problem. At one point I had so many compiler errors that I wondered if adding MQTT had completely destroyed a project that had worked perfectly the day before.
The funny thing about debugging is that once you've spent enough hours staring at code, you automatically assume the bug must be hiding somewhere inside the code.
This time it wasn't.
After tracing the entire communication path between the ESP32, Mosquitto, MQTTX, and my computer, I discovered that everything was actually configured correctly. The broker was running. The topics were correct. The ESP32 was connected to Wi-Fi.
The real culprit was Windows Defender Firewall.
A single firewall setting was silently blocking MQTT traffic between the ESP32 and my computer.
After temporarily disabling the firewall, the serial monitor immediately changed from:
"Connecting MQTT... failed"
to
"Connecting MQTT... connected!"
The speaker responded. MQTT messages flowed. Everything suddenly worked.
The experience reminded me of something I often see in engineering: when a system involves hardware, firmware, networking, operating systems, and third-party software, the bug may live in a completely different layer than the one you're currently investigating.
Sometimes the problem isn't the code.
Sometimes the problem isn't even on the microcontroller.
Sometimes the problem is a checkbox hidden somewhere inside Windows.
And somehow those are always the bugs that take the longest to find. :D
I am going to film a short summary video to celebrate this project soon! Coming soon...
But please enjoy a few clips of the project
Part 1: Start
Part 2: Website control ESP32-S3
Part 3: MQTTX control ESP32-S3
Comments