Troubleshooting
Troubleshooting
Diagnose setup, build, flash, preview, generated-code and runtime problems.
Setup and launch
| Problem | Check |
|---|---|
| Studio does not launch | Run npm install in the Studio workspace; confirm Node.js 20 and that the expected local port is free. |
| Node or npm missing | Install Node.js 20 LTS, reopen the terminal and rerun first-time setup. |
| ESP-IDF environment inactive | Use an ESP-IDF 5.5.x terminal or activate the environment before external idf.py commands. |
| Device port not found | Check USB data cable, board power, Windows Device Manager and serial drivers. |
Build and flash
| Problem | Check |
|---|---|
| Build fails | Read the first compiler error; verify ESP-IDF 5.5.4 and exported source registration. |
| Stale generated output | Use Clean Build & Flash, then inspect the regenerated CMake sources. |
| Screen remains black | Confirm target profile, display initialization, flashed partition and that generated UI creation is called. |
| Flash-size pressure | Review converted asset dimensions, color format and partition usage. |
UI and runtime
| Problem | Check |
|---|---|
| Asset missing | Confirm the asset passed export validation and appears in CMakeLists.txt. |
| Callback unresolved | Match the generated declaration and exact hook name in 95_UserEvents.c / .h. |
| UI differs from Preview | Check exported geometry, font availability, native widget styling and target-specific rendering. |
| Generated file edited accidentally | Restore from Git and move permanent logic to developer-owned code. |
| Wi-Fi or storage unavailable | Verify the corresponding firmware backend, board configuration and physical media/transport. |
| Hardware boots but UI is absent | Use idf.py monitor and verify app startup reaches the generated UI registration call. |