Troubleshooting Index
Search this page (Ctrl+F) for your error message before posting.
GrapesIDE & Toolchain
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
ESP32 Hardware
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
FreeRTOS
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
MQTT & Connectivity
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
GrapesIoT Platform
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
GrapesIDE Specific
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.