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)

“connect ECONNREFUSED 127.0.0.1:9998”

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?