<![CDATA[🔍 Troubleshooting Index — Error Messages & Solutions [SEARCH HERE FIRST]]]>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.

]]>https://forum.grapesiot.com/topic/12/troubleshooting-index-error-messages-solutions-search-here-firstRSS for NodeWed, 22 Jul 2026 09:23:15 GMTWed, 22 Jul 2026 06:23:31 GMT60