Troubleshooting FAQ

Generic Issues

USB Adapter Is Not Connected

OpenOCD log looks like below.

Error: unable to open ftdi device with vid 0403, pid 6010, description '*', serial '*' at bus location '*'

or

Error: esp_usb_jtag: could not find or open device!

and/or

Error: libusb_open() failed with LIBUSB_ERROR_NOT_FOUND

Reason	Adapter type	Solution
Wrong board configuration file.	Any	Ensure that you use proper board configuration file for connected HW. NOTE: For chips coming with builtin USB-JTAG interface it is used as default one. See more documentation on DIS_USB_JTAG and JTAG_SEL_ENABLE efuses on how to switch to JTAG pins pad.
No debug adapter is connected.	Any	Check that the debug adapter USB device is present in the system. Windows: Go to Device Dispatcher and check that device is detected by the system. Linux: Use lsusb to list all connected USB devices. MacOS: system_profiler SPUSBDataType or brew install lsusb and use lsusb to list all connected USB devices.
Debug adapter's driver was installed incorrectly.	Any	Similar issue discussions. Windows: Install driver using IDF Tools Installer. Also see ESP-IDF related docs. Linux: See ESP-IDF related docs. MacOS: See ESP-IDF related docs.
Espressif USB-JTAG is disabled via efuses.	Builtin	Check DIS_USB_SERIAL_JTAG and DIS_USB_JTAG efuses.

JTAG Connection Is Bad

OpenOCD log looks like the below.

Error: JTAG scan chain interrogation failed: all zeroes
Error: Check JTAG interface, timings, target power, etc.
Error: Trying to use configured scan chain anyway...

Reason	Adapter type	Solution
JTAG wires are connected improperly.	External	Similar issue discussion.
Application reconfigured JTAG pins for other purposes (e.g. SPI or SDMMC).	External	Similar issue discussion. Make your application using other pins.
JTAG wires are too long or HW connection is poor.	External	Double check connecting wires. Try to use shorter wires for JTAG or lower the adapter speed with -c 'adapter speed <speed_in_khz>' command line option.
Espressif USB-JTAG is disabled via JTAG interface selecting efuse.	Builtin	Check JTAG_SEL_ENABLE efuse and corresponding GPIO strapping pin.

USB Communication Issue

OpenOCD log looks like the below.

Error: 113 485 libusb_helper.c:373 jtag_libusb_get_serial(): libusb_get_string_descriptor_ascii() failed with -9

The error code -9 corresponds to LIBUSB_ERROR_PIPE, which generally indicates that the target can not respond to the OpenOCD command. There is no unique solution. Check all possible reasons listed below and try to fix them.

Reason	Solution
USB connection issues.	Ensure that the USB cable is properly connected between the host computer and the chip. Check for any physical damage to the USB cable or connectors.
Driver issues.	Make sure that the appropriate USB drivers are installed for the chip on the host computer. Verify that the USB drivers are up-to-date.
Power supply.	Insufficient power supply to the chip might lead to USB communication problems. Ensure that the chip is adequately powered.
Floating bootstrap pins.	For some chips (eg. ESP32-C3) floating bootstrap pins can cause USB communication problems. Ensure that the bootstrap pins are not left in the float mode for proper functionality.

GDB Communication Issue

GDB output looks like below.

Ignoring packet error, continuing...
warning: unrecognized item "timeout" in "qSupported" response
Remote replied unexpectedly to 'vMustReplyEmpty': PacketSize=4000;qXfer:memory-map:read+;qXfer:features:read+;qXfer:threads:read+;QStartNoAckMode+;vContSupported+

Usually this means that OpenOCD becomes unresponsive due to:

Reason	Solution
Slow communication with target.	Similar issue discussion. Increase GDB remote timeout Increase debug adapter speed by adding -c adapter_khz XXX at the end of OpenOCD command line or change it in the config file
High verbosity of debug output (enabled with -d3).	Similar issue discussion. See solutions above.

Flash Related Issues

Uploading FW Not Working

OpenOCD log at startup looks like the below.

WARNING: ESP flash support is disabled!
WARNING: ESP flash support is disabled!

When user tries to flash program binary OpenOCD log looks like the below

embedded:startup.tcl:1813: Error: ** ESP flash programming is not supported! **
in procedure 'program_esp'
in procedure 'program_error' called at file "/home/user/.espressif/tools/openocd-esp32/v0.12.0-esp32-20241016/openocd-esp32/share/openocd/scripts/target/esp_common.cfg", line 407
at file "embedded:startup.tcl", line 1813

or like below

embedded:startup.tcl:1813: Error: ** ESP flash programming is not supported! **
in procedure 'program_esp_bins'
in procedure 'program_error' called at file "/home/user/.espressif/tools/openocd-esp32/v0.12.0-esp32-20241016/openocd-esp32/share/openocd/scripts/target/esp_common.cfg", line 540
at file "embedded:startup.tcl", line 1813

Reason	Solution
Flash support is disabled because it has not been implemented for that chip yet.	Flash FW over UART.
Flash support is disabled via OpenOCD command line by option -c 'set ESP_FLASH_SIZE 0'.	Remove that command line option or flash FW over UART.

Application Binary Image Problem

Mostly, warnings can be seen in 2 different forms.

Warn : Failed to get flash maps (-8)!
Warn : Invalid magic number in app image!
Warn : Failed to get flash mappings (-4)!

or

Warn : Failed to get flash maps (-6)!
Warn : Application image is invalid! Check configured binary flash offset 'appimage_offset'.
Warn : Failed to get flash mappings (-4)!

Reason	Solution
The partition table is not at default (0x8000) address, so OpenOCD failed to locate application image in flash.	Set application image offset explicitly using command line option: openocd -f <board_config> -c "init; halt; esp appimage_offset <new_app_binary_offset>"
Application is not loaded to flash or unexpected magic number read from its location.	Load the application to flash and try again.

Flash Chip Detection Problem

OpenOCD log looks like below.

Warn : Failed to get flash maps (-9)!
Warn : Failed to read flash size!
Warn : Failed to get flash mappings (-4)!
Error: Failed to probe flash, size 0 KB

Reason	Solution
This indicates that stub failed to detect flash chip size. There can be various reasons for it.	To diagnose root cause for this problem we need to analyze flasher stub log. So, please, collect by running OpenOCD like openocd ..... -f board/esp32s3-builtin.cfg -c "esp stub_log on" and attach it to the reported issue. Refer to this issue as an example.

Flasher Stub Execution Problem

OpenOCD log looks like below.

Error: Algorithm run failed (-302)!
Error: Failed to run flasher stub (-302)!

Reason	Solution
This indicates serious flasher stub problem. It can get stuck due to the exception happened, waiting for response from HW or any other reason or just met abnormal conditions and returned abruptly.	To diagnose root cause for this problem we need to analyze flasher stub log. So, please, collect by running OpenOCD like openocd ..... -f board/esp32s3-builtin.cfg -c "esp stub_log on" and attach it to the reported issue. Refer to this issue as an example.

Chip-Specific Issues

Failed To Start Application Level Tracing On RISCV Chip

OpenOCD log looks like below.

Error: Failed to get max trace block size!
Error: Failed to init cmd ctx (-4)!

Reason	Solution
For Espressif RISCV chips you need to reset the target after OpenOCD is connected to trigger apptrace control info transfer from the target to OpenOCD. It is done by invoking a special syscall when apptrace is initialized on the target during startup.	Reset chip after OpenOCD is connected and then start tracing. Use GDB to start tracing like mon esp apptrace start .... When GDB is connected to OpenOCD chip is reset automatically.

ESP32-C3 and ESP32-S3 builtin USB_JTAG gets stuck after HW reset

OpenOCD log after target HW reset looks like below.

Error: esp_usb_jtag: usb sent only 0 out of 31 bytes.
Error: missing data from bitq interface
Error: esp_usb_jtag: usb sent only 0 out of 50 bytes.
Error: missing data from bitq interface
Error: Failed to exec JTAG queue!
Error: Failed to read debug stubs address location (-104)!

Reason	Solution
Known issue 1 Known issue 2	Solved by commit.

ESP32-S3 flash access problem using builtin USB_JTAG

OpenOCD log looks like below when flash is accessed (e.g. upon GDB connect).

Error: esp_usb_jtag: usb sent only 0 out of 31 bytes.
Error: missing data from bitq interface
Error: esp_usb_jtag: usb sent only 0 out of 50 bytes.
Error: missing data from bitq interface
Error: Failed to exec JTAG queue!
Error: Failed to read debug stubs address location (-104)!

Reason	Solution
This is a known issue.	The workaround is to use an external JTAG adapter or run OpenOCD with disabled flash support with option -c 'set ESP_FLASH_SIZE 0'.

ESP32-C3 'JTAG_SEL_ENABLE' efuse does not work in silicon rev3

Reason	Solution
This is known issue of rev3 silicon.	https://github.com/espressif/esp-idf/issues/7836

Non-Espressif Debug Adapters

TBD

General OpenOCD Features

Profiling: xtensa-esp-elf-gprof: can't find .text section in X.elf

https://github.com/espressif/openocd-esp32/issues/312

Reason	Solution
gprof searches for a .text section in the compiled binary to generate a report. However, ESP-IDF application ELF files have a .flash.text section.	To resolve this, replace .flash.text with .text using the following command: xtensa-esp32s3-elf-objcopy -I elf32-xtensa-le --rename-section .flash.text=.text <app.elf>