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

[Author]

Posts