ESP32 Arduino: wrong GDB path / KeyNotFound core 3.3.12

[ImHoTep]

Hello Sysprogs team,

I’m trying to debug an Arduino project for the ESP32 with VisualGDB, and I’m running into two problems that seem to be related to how VisualGDB handles the ESP32 Arduino core. I would be very grateful for a hint on how to resolve them.

Environment
– VisualGDB 6.1.103.5547 (latest version according to the update check)
– Arduino ESP32 core (esp32 by Espressif Systems) 3.3.12
– Board: ESP32 Dev Module
– Debug interface: ESP32 DevKit (FTDI), “Debug using: ESP32 Devkit”, JTAG frequency 3000 kHz

The hardware side works fine: OpenOCD detects both cores (esp32.tap0/tap1, “Examination succeed”), starts the GDB server and halts the target. Uploading without debugging also works without any issues.

Some background: I have been trying to get ESP32 Arduino debugging working in VisualGDB with various core versions over time, and I always ran into the same kind of problem. It worked only once, with an early version, but unfortunately I don’t remember which one. With the same hardware, debugging in PlatformIO has always worked with the previous core versions I used (I haven’t tested 3.3.12 there yet). I have also seen similar questions from other users in your forum, but I couldn’t find a solution that applies to my case.

Problem 1 – “Program FLASH using: OpenOCD (via JTAG)”
Debugging fails with “Der angegebene Schlüssel war nicht im Wörterbuch angegeben” (KeyNotFoundException):

System.Collections.Generic.KeyNotFoundException
at System.Collections.Generic.Dictionary`2.get_Item(TKey key)
at ESP8266DebugPackage.ESP32StartupSequence.BuildFLASHImages(String targetPath, Dictionary`2 bspDict, ESP32ImageHeader flashSettings, Boolean patchBootloader)
at ESP8266DebugPackage.ESP32DebugController.BuildProgrammableBlocksFromSettings(IDebugStartService service, IESP32Settings settings)
at ESP8266DebugPackage.ESP32DebugController.LoadFLASH(…)
at ESP8266DebugPackage.ESP32DebugController.ESP32GDBStub.RunLoadCommand(…)
at OpenOCDPackage.OpenOCDDebugController.OpenOCDGDBStub.ConnectGDBToStub(…)

Setting “Program FLASH memory” to “Never” does not change this. I assume this is because the startup GDB commands still contain “load”. It looks as if a property expected by VisualGDB is missing in the board definitions of the core.

Problem 2 – “Program FLASH using: Arduino tools”
The exception above disappears, but GDB exits immediately (“GDB session exited prematurely”). VisualGDB tries to start GDB from the compiler package:

C:\Users\info\OneDrive\Dokumente\ArduinoData\packages\esp32\tools\esp-x32\2601\bin\xtensa-esp32-elf-gdb –interpreter mi “…\ArduinoProject1.ino.elf”

This file does not exist. In core 3.x, GDB is shipped as a separate package:

…\packages\esp32\tools\xtensa-esp-elf-gdb\17.1_20260402\bin\xtensa-esp32-elf-gdb.exe

This GDB runs fine from the command line (“GNU gdb (esp-gdb) 17.1_20260402”), and it is correctly listed under Arduino Project -> “Use specific tool versions” (xtensa-esp-elf-gdb = …\17.1_20260402). However, VisualGDB still derives the GDB path from the esp-x32 compiler folder. Changing “JTAG Adapter” to “FTDI Adapter” did not change the GDB path either.

My questions
1. Is the ESP32 Arduino core 3.3.x supported by VisualGDB 6.1, or is an update planned?
2. Is there a way to specify the GDB executable for an Arduino project manually, so that VisualGDB uses the separate xtensa-esp-elf-gdb package?
3. Is there a known workaround for the KeyNotFoundException in BuildFLASHImages when programming the FLASH via OpenOCD?
4. If core 3.3.x is not supported yet: which core version would you recommend for ESP32 Arduino debugging with VisualGDB 6.1?

I’m happy to provide screenshots of the project properties, the complete OpenOCD log or the low-level GDB log if that helps.

Thank you very much for your help!

Best regards,
Thomas

[support]

Thanks, we have reproduced the problem. Espressif indeed changed the internal layout of the tools in this version, so detecting gdb from the gcc path doesn’t work anymore. VisualGDB 6.1 was released when the old core layout was in place, so it won’t recognize the new one.

We have added support for the new core layout to the upcoming VisualGDB 6.2, however it is still a development build with a few rough edges here and there. You can try using the stand-alone version based on our CodeVROOM shell [CodeVROOM-0.8.0.367.exe] for the new ESP32 Arduino core, and keep VisualGDB 6.1 with Visual Studio for the other projects until v6.2 is more reliable. We can also publish the VisualGDB 6.2 build that includes the fix, but it cannot be installed simultaneously with v6.1.

[ImHoTep]

Hello Sysprogs team,

Thank you very much for reproducing the problem and for the detailed explanation, that helps a lot.

Since my VisualGDB 6.1 setup is working reliably for my ESP-IDF projects, I would prefer not to replace it with a development build. I will wait for a stable release of VisualGDB 6.2 (and CodeVROOM) and will be happy to test the new Arduino core support then.

In the meantime, I found a workaround that works well with VisualGDB 6.1, and I’d like to share it in case it is useful for you or other users. I use the Arduino core as an ESP-IDF component in a regular VisualGDB ESP-IDF project:

– ESP-IDF 6.1.0, ESP32 (Consolidated) toolchain
– espressif/arduino-esp32 4.0.0-rc1 from the ESP Component Registry (based on ESP-IDF 6.1)
– Tested on ESP32 (FTDI JTAG) and ESP32-S3 (built-in USB-JTAG): build, flash, breakpoints, stepping and terminal all work.

Changes required on a freshly generated project:

1. main/idf_component.yml: dependency espressif/arduino-esp32: “4.0.0-rc1”
2. sdkconfig: CONFIG_FREERTOS_HZ=1000
3. sdkconfig: CONFIG_MBEDTLS_PSK_MODES=y and CONFIG_MBEDTLS_KEY_EXCHANGE_PSK=y (required by NetworkClientSecure)
4. Top-level CMakeLists.txt, before project(): idf_build_set_property(COMPILE_OPTIONS “-Wno-error=missing-field-initializers” APPEND) (ESP_I2S.cpp in the RC1 vs. new fields in i2s_chan_config_t)
5. Top-level CMakeLists.txt, after project(): -Wno-error=cpp for the Arduino component only (on ESP32-S3, ESP_SR emits a #warning about the partition table):
idf_component_get_property(arduino_lib espressif__arduino-esp32 COMPONENT_LIB)
target_compile_options(${arduino_lib} PRIVATE -Wno-error=cpp)
6. Main source converted to .cpp, app_main declared extern “C” and calling initArduino().
7. Advanced GDB Settings: “Use file names only when setting breakpoints” (UseRelativePathsOnly) enabled.

I have automated all of these steps in a small Python script (attached, standard library only). Usage:

1. Create a new ESP-IDF project with the VisualGDB wizard and let it configure once.
2. Unload the project in Visual Studio.
3. Copy idf_arduino_setup.py into the project root (next to sdkconfig and the .vgdbproj file) and run it (double-click or “python idf_arduino_setup.py”).
4. Reload the project and build. The first build downloads the Arduino core.

The script creates .bak backups of all modified files and can safely be run multiple times.

Two observations that might be worth checking in 6.2, since your reply only covered the GDB path:

– With “Program FLASH using: OpenOCD”, the Arduino project type failed with a KeyNotFoundException in ESP32StartupSequence.BuildFLASHImages (core 3.3.12, ESP32 Dev Module).
– Point 7 above: without this option, Visual Studio froze or crashed and restarted itself as soon as the target stopped at a breakpoint. The GDB log ended in the middle of the response to -file-list-exec-source-files. With the Arduino core and its dependencies, this source file list becomes very large. This might also affect the Arduino project type in 6.2.

Thank you again for your support.

Best regards,
Thomas

[ImHoTep]

Sorry, I could’ not upload the script here.
Go:
https://mindmake.de/dl/visualgdb/

 

[Author]

Posts