Where to look for indications of the problem

The Espressif troubleshooting page has a good guide (and is what they’ll probably ask you for if you request help)

Useful troubleshooting changes you can do in in launch.json
//More logging info:
"logLevel": 3,
//Even more logging info:
"logLevel": 4,

//Give more timeout time for things that take a while:
"tmoScaleFactor": 4,

JTAG debugging issues we’ve encountered (using ESP-Prog and VSCode)


In launch.json, changing mode to auto seems to solve this: “mode”: “auto”,

Use EDP-IDF Flash Device first (lighting button in bottom blue toolbar).

Close the OpenOCD Server (press the OpenOCD Server (Running) button in the bottom blue tool bar. Then press again to restart it (selecting the option on the top command box each time).

“Failed to init Debug Adapter!”

Did programming fail?

Check the OUTPUT window for the program operation didn’t have errors. If it does, check:

Does your device has eFuses that need to be burnt to enable the JTAG pins? The ESP32S3 , ESP32C3, etc does – see here.

OUTPUT window shows “ERROR – Failed to wait for completion of command”

In launch.json, changing tmoScaleFactor from 1 to 2 or higher can solve this: “tmoScaleFactor”: 2,

“Error: OpenOCD only supports Debug Module version” ….. “This error might be caused by a JTAG signal issue. Try reducing the JTAG clock speed”

Are you driving the JTAG pins in your application? When using the JTAG interface via the IO you must not drive the pins.  You’ll need to re-program using the UART to clear this issue.

Serial debugging issues we’ve encountered (using ESP-Prog and VSCode)

waiting for download (esp-idf halts at this line)

Is the GPIO# line that is used to select Normal mode / Bootloader mode for the ESP32 stuck low, i.e. because your circuit is sharing it and something has pulled it low?

We benefit hugely from resources on the web so we decided we should try and give back some of our knowledge and resources to the community by opening up many of our company’s internal notes and libraries through mini sites like this. We hope you find the site helpful.
Please feel free to comment if you can add help to this page or point out issues and solutions you have found, but please note that we do not provide support on this site. If you need help with a problem please use one of the many online forums.


Your email address will not be published. Required fields are marked *