🔍 Troubleshooting Index — Error Messages & Solutions [SEARCH HERE FIRST]

admin

Troubleshooting Index

Search this page (Ctrl+F) for your error message before posting.

Error	Cause	Solution
`A fatal error occurred: Failed to connect to ESP32`	Board not in flash mode	Hold BOOT button while clicking Upload
`No serial port found`	Driver not installed	Install CH340 or CP2102 driver
`Sketch too large`	Binary exceeds flash	Change Partition Scheme to "No OTA (2MB)"
`'x' was not declared in this scope`	Missing #include or typo	Add the correct header file
`implicit conversion loses integer precision`	Type mismatch	Cast explicitly or fix variable type
`warning: unused variable`	Variable declared but never used	Remove or use the variable. Enable -Werror — this must be fixed

Error / Symptom	Cause	Solution
ADC reads 0 or noise during WiFi	ADC2 conflicts with WiFi	Switch to ADC1 channels (GPIO32-39)
GPIO reads random values (floating)	No pull-up/pull-down	Add 10kΩ pull-up or enable internal pull-up
Device resets randomly	Brownout — supply voltage too low	Measure VCC under load. Use better USB cable/adapter
Serial output garbled	Wrong baud rate in monitor	Match Serial.begin() rate exactly
LED on but dim	GPIO current limit exceeded	Add current-limiting resistor

Error / Symptom	Cause	Solution
`Guru Meditation Error: Core panic'd`	Stack overflow, null deref, WDT	Decode with addr2line — see Block 2 Crash Lab
`Task watchdog got triggered: taskName`	Task running without vTaskDelay	Add vTaskDelay(pdMS_TO_TICKS(1)) in loop
Device freezes randomly	Deadlock between mutexes	Check mutex acquisition order — always same order across tasks
`assert failed: queue.c`	Queue full with no space	Increase queue size or consume faster
Device reboots every N seconds	WDT not being reset	Add esp_task_wdt_reset() or vTaskDelay in busy tasks

Error / Code	Cause	Solution
PubSubClient state `-2` (CONNECT_FAILED)	Wrong credentials or broker down	Check username/password/token
PubSubClient state `-4` (TIMEOUT)	Wrong broker IP/port, firewall	Verify host, port 8883 for TLS
PubSubClient state `5` (UNAUTHORIZED)	ACL blocked the topic	Check topic matches your device_id exactly
TLS `certificate verify failed`	Wrong CA cert or device clock wrong	Sync NTP before TLS connect
TLS `handshake timeout`	Heap too low for TLS	Need >50KB free heap — check esp_get_free_heap_size()
WiFi connects but MQTT fails	TLS port blocked by ISP/router	Try port 8083 (WS) or check firewall rules
Messages not arriving	QoS mismatch	Check publisher and subscriber QoS match

Symptom	Cause	Solution
Device shows offline in dashboard	LWT not configured or WiFi down	Check MQTT connection and LWT topic
OTA command sent but device ignores	Device not subscribed to /down/#	Check subscription in firmware
Dashboard shows old data	Retained message from previous session	Clear retained by publishing empty payload
Alarm not triggering	Wrong field path in rule config	Check dot-notation path matches payload key

Issue	Solution
Autocomplete not working	Restart IntelliSense: Ctrl+Shift+P → Reload Window
Board not detected on Mac	Allow USB accessories in System Settings → Privacy
Build slow	Exclude .pio folder from antivirus

Last updated by instructor. Post below if you have a new error+solution to add.