Esp32 Log Triage

ESP32 Log Triage

Systematically analyze ESP32 serial log output to identify and classify issues.

When to Use

• Debugging unexpected device behavior.
• Analyzing boot failures.
• Reviewing log output after a test run.
• Triaging field-reported issues from log captures.

Steps

1. Identify Log Structure

ESP-IDF log format:

[LEVEL][TAG] (TIMESTAMP) MESSAGE

Levels (severity order):

• E — Error (critical failures)
• W — Warning (potential issues)
• I — Info (normal operation)
• D — Debug (detailed tracing)
• V — Verbose (maximum detail)

2. Extract Critical Events

Search for these high-priority patterns:

Boot Failures

rst:0x1 (POWERON_RESET)          → Normal power-on
rst:0x3 (SW_RESET)               → Software reset
rst:0x7 (TG0WDT_SYS_RESET)      → Task watchdog reset
rst:0x8 (TG1WDT_SYS_RESET)      → Interrupt watchdog reset
rst:0xf (BROWNOUT_RESET)         → Power supply issue

Crash Signatures

Guru Meditation Error             → CPU exception
LoadProhibited                    → NULL pointer or invalid memory read
StoreProhibited                   → Write to invalid memory
InstrFetchProhibited              → Jump to invalid address
IllegalInstruction                → Corrupt code or stack
abort()                           → Software abort
Stack overflow                    → Task stack too small

Memory Issues

MALLOC_FAILURE                    → Heap exhaustion
heap_caps_alloc failed            → Specific heap type exhausted
heap corruption detected          → Memory corruption

Network Issues

wifi:state:                       → Wi-Fi state transitions
esp_netif_lwip: Failed            → Network interface errors
TRANSPORT_BASE: Failed            → Connection failures
MQTT_CLIENT: Error                → MQTT protocol errors

3. Classify the Issue

Categorize the primary issue:

| Category | Indicators | |----------|-----------| | Boot loop | Repeated reset reasons, never reaches app_main | | Crash | Guru Meditation, backtrace present | | Memory | Allocation failures, usage growing over time | | Watchdog | TG0WDT/TG1WDT reset reasons | | Network | Connection failures, timeouts, drops | | Peripheral | I2C/SPI/UART errors, timeout on bus | | Power | Brownout resets, unstable ADC readings |

4. Extract Backtrace

If a crash backtrace is present:

Backtrace: 0x400d1234:0x3ffb5678 0x400d2345:0x3ffb6789

Decode with:

xtensa-esp32-elf-addr2line -pfiaC -e build/project.elf 0x400d1234 0x400d2345

5. Generate Triage Report

# Log Triage Report

## Summary
- **Issue type**: [Boot loop / Crash / Memory / Watchdog / Network / Peripheral / Power]
- **Severity**: [CRITICAL / HIGH / MEDIUM / LOW]
- **Reset reason**: [From boot log]

## Key Events (chronological)
1. [timestamp] [event description]
2. [timestamp] [event description]

## Error Patterns
- [Pattern]: [count] occurrences — [interpretation]

## Root Cause Hypothesis
[Most likely cause based on evidence]

## Recommended Next Steps
1. [Action]
2. [Action]

## Raw Evidence
[Relevant log excerpts]

Tips

• Brownout resets usually indicate insufficient power supply, not code bugs.
• Watchdog resets during Wi-Fi often mean a task is blocking the system task.
• Guru Meditation with address 0x00000000 is almost always a NULL pointer dereference.
• Repeated MQTT disconnects — check keepalive interval vs. network latency.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: agodianel
• Source: agodianel/esp32-claude-workbench
• License: MIT

Install and usage instructions live in the source repository linked above.