esp32-build-fix
Diagnoses and fixes ESP-IDF build, link, CMake/Kconfig, component-manager and flashing failures, using the build log to classify the error before changing anything. Use when "idf.py build fails", "undefined reference to", "No such file or directory" for a header, "Failed to resolve component", "CMake Error", "multiple definition of", "region `iram0_0_seg' overflowed", "app partition is too small", "implicit declaration of function", "esptool Failed to connect", "Wrong boot mode detected", "No serial data received", "Permission denied /dev/ttyUSB0", "A fatal error occurred", "set-target", or after an ESP-IDF version upgrade (v4 → v5) breaks the build.
agodianel · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add agodianel/esp32-claude-workbench --skill esp32-build-fix技能说明
name: esp32-build-fix description: Diagnoses and fixes ESP-IDF build, link, CMake/Kconfig, component-manager and flashing failures, using the build log to classify the error before changing anything. Use when "idf.py build fails", "undefined reference to", "No such file or directory" for a header, "Failed to resolve component", "CMake Error", "multiple definition of", "region `iram0_0_seg' overflowed", "app partition is too small", "implicit declaration of function", "esptool Failed to connect", "Wrong boot mode detected", "No serial data received", "Permission denied /dev/ttyUSB0", "A fatal error occurred", "set-target", or after an ESP-IDF version upgrade (v4 → v5) breaks the build. license: MIT metadata: source: esp32-workbench version: "0.2.0"
ESP32 Build & Flash Fix
Classify first, then make the smallest fix. Never "fix" a build by deleting configuration the user cares about.
Tools
If the esp32-workbench MCP server is connected, call its tools; otherwise run the
CLI. If esp32wb is not on PATH, use
uvx --from git+https://github.com/agodianel/esp32-claude-workbench esp32wb <args>.
Add --json for machine-readable output.
| Need | MCP tool | CLI |
|---|---|---|
| Classify build / flash output | build_log_triage | idf.py build 2>&1 | tee build.log; esp32wb build-log build.log (or ... | esp32wb build-log -) |
| App vs partition size | partition_check | esp32wb partitions partitions.csv --sdkconfig sdkconfig --bin build/<app>.bin |
| sdkconfig sanity | sdkconfig_review | esp32wb sdkconfig sdkconfig |
| Chip facts (toolchain, USB/strapping pins for download mode) | chip_info | esp32wb chip <target> |
| API changed / renamed? | search_esp_docs | esp32wb docs search "<symbol or error>" --target T |
Steps
1. Capture the full first error
Rerun with output captured (idf.py build 2>&1 | tee build.log). The first
error matters; later ones are usually cascades. Run esp32wb build-log build.log.
2. Establish context
idf.py --versionand the version the project expects (README, CI,idf_component.ymldependencies.idf).- Target:
CONFIG_IDF_TARGETinsdkconfigvs the board you have. A stalesdkconfigfrom another target causes many confusing errors. - Was it building before? What changed (IDF upgrade, new component, new target,
managed_componentsupdate)?
3. Classify and fix
| Category | Signature | Usual fix |
|---|---|---|
| Missing header | fatal error: xyz.h: No such file or directory | Add the owning component to REQUIRES/PRIV_REQUIRES; in recent IDF v5.x releases drivers are split into esp_driver_* components (e.g. esp_driver_gpio, esp_driver_i2c) — driver still works as an umbrella |
| Linker | undefined reference to | Source not in SRCS, missing REQUIRES, C/C++ name mangling (extern "C"), Kconfig option disabling the feature |
| Duplicate symbol | multiple definition of | Function defined in a header without static inline, or same file compiled twice |
| Kconfig | 'CONFIG_X' undeclared | Option renamed/removed in this IDF version or not enabled; check sdkconfig and IDF migration guide |
| Component manager | Failed to resolve component, version solver errors | Fix idf_component.yml constraints; idf.py update-dependencies |
| API change after upgrade | implicit declaration, unknown type name | Follow the ESP-IDF migration guide (ADC → adc_oneshot, I2C → i2c_master driver, legacy timer/RMT/I2S drivers replaced) |
| Memory overflow | region 'iram0_0_seg' overflowed, dram0_0_seg overflow | Move code out of IRAM, reduce static buffers, enable PSRAM for large buffers |
| App too big | app partition is too small / partition check fails | Larger app partition or custom partitions.csv, -Os (CONFIG_COMPILER_OPTIMIZATION_SIZE), drop unused features |
| Target mismatch | static assertions, missing SoC symbols | idf.py set-target <target> (this regenerates sdkconfig) |
| Toolchain / env | xtensa-...-elf-gcc: not found, riscv32-esp-elf-gcc: not found, Python env errors | Re-run install.sh <target> / export.sh for the IDF version in use |
Details and examples: build failure playbook.
4. Flash and monitor failures
Read flash failure playbook for esptool errors
(Failed to connect, Wrong boot mode detected, No serial data received,
permission denied, invalid header boot loops after flashing). Download-mode entry
and the USB port differ per chip — check esp32wb chip <target> for the boot strapping
pins and USB-Serial-JTAG pins.
5. Verify
- Clean build of the affected configuration (
idf.py fullclean && idf.py buildonly after the targeted fix, to prove it is not a stale-cache artifact). - No new warnings.
- If flashing was the issue: flash + boot log showing
app_mainreached. - Record commands and output as test evidence in the mission.
Safety
idf.py set-targetand deletingsdkconfigdiscard local menuconfig changes. Back upsdkconfigfirst and make suresdkconfig.defaultscaptures what matters.idf.py erase-flashwipes NVS (Wi-Fi credentials, calibration, bonds). Ask first.- Never burn eFuses or enable secure boot/flash encryption to "fix" a flash error.
- A code change made to fix the build still needs a (brief) implementation contract.