Interesting results re: chronic ESP-PROG problems

Disclaimer: I am a beginner!

I have been tearing my hair out trying to figure out why the ESP-PROG is giving me so many problems. I have found many other threads about this asking similar questions with little/no progress, so I’m posting some findings here in case they are helpful.

TLDR: debugging seems to fail when the amount of written flash (or amount of memory used?) gets beyond a certain point; after that it continues to fail until a smaller sketch is uploaded in regular (not-debug) mode. Then you can upload the large sketch one time, but it will fail thereafter.

Me: ESP32-DevKitCVIE (WROVER-IE) on vscode/pio in linux. I’ve been debugging OK with the ESP-PROG on a project for a while. Recently it started getting more flaky: requiring restarting the ESP-PROG, unplugging and replugging things, etc. More recently it stopped working at all and I could not debug at all.

Main symptom is that after F5, it builds the project and the debugging console will hang after a “** Programming Started **” line and eventually bail with a lot of “timed out while waiting for target halted” / “Failed to wait algorithm” / “Target is already running an algorithm” / “Failed to start algorithm” etc.

Example where it goes off the rails:

** Programming Started **
** Programming Started **
Error: timed out while waiting for target halted
timed out while waiting for target halted
Info : [esp32.cpu0] Target halted, PC=0x400904F2, debug_reason=00000000
[esp32.cpu0] Target halted, PC=0x400904F2, debug_reason=00000000
Error: xtensa_wait_algorithm: not halted 0, pc 0x400904f2, ps 0x60025
Error: Failed to wait algorithm (-302)!
Error: Algorithm run failed (-302)!
xtensa_wait_algorithm: not halted 0, pc 0x400904f2, ps 0x60025
Failed to wait algorithm (-302)!
Algorithm run failed (-302)!
Error: Target is already running an algorithm
Error: Failed to start algorithm (-4)!

I spent hours today trying to figure out the patterns, and this is the (terrible, but reliable) work-around I have come up with:

  1. switch to a smaller project (or comment out some code and/or #include’s in your project to get the size down) (or erase flash with
  2. do a regular non-debug upload (I have to unplug the ESP-PROG USB cable to do this even though I don’t use upload_protocol=esp-prog – I suspect a separate bug?)
  3. switch back to the large project and hit F5
  4. it will work, but only one time, and you have to go back to step (1) to get it to work again.

You have to switch to a “small” project, and you have to do a non-debug upload to fix it. Trying to do a non-debug upload of the “large” project will not fix it. Trying to do a debug upload of a “small” project will not work, and will not fix it.

My “large” project uses about 79% of the flash. Successful debug logs show that it’s uploading 1044480 bytes. Again, this only works one time, then it is “broken” until the procedure above is followed.

A “small” project can be debugged over and over without issue.

I tried updating openocd to the latest (v0.12.0-esp32-20230921) but it didn’t work at all – tons of errors and failures in the debug console. Maybe because platformio isn’t expecting it?

Is this more likely to be an openocd issue than a platformio issue? If so, I’m not sure how I can report it, because they will of course ask me to use the latest version but it doesn’t work at all in vscode/PIO (at least when I tried it.)

Other threads with a similar issue:

My platformio.ini in case it’s relevant:

platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
monitor_port = /dev/ttyUSB0
monitor_filters = esp32_exception_decoder
build_flags = -DBOARD_HAS_PSRAM
lib_deps = 
	adafruit/Adafruit BusIO@^1.14.5
	adafruit/Adafruit Unified Sensor@^1.1.13
	adafruit/Adafruit SHT4x Library@^1.0.4
debug_tool = esp-prog
debug_init_break = tbreak setup

Hi, I need to also share my frustration with solnd and the boat load of users in the many many Google queries I’ve run regarding the whole PlatformIO, GDB, JTAG debugging paradigm. I share the same issues with almost all of the various users who’ve attempted to debug code like a “grown-up” using the JTAG/GDB combination in PIO. The paradigm, debugging with the software mentioned, is consistently inconsistent. I’m sorry I know this isn’t of much help, but what I’ve experienced has lead me to this level of frustration. Please don’t get me wrong, when debugging works through the JTAG/GDB it works well, but the other 75% of the time its of no use and has greatly increased my whiskey consumption.

An example of what I typically run into is as follows: if/when I get debugging to work it’s great, then I go to lunch, return from lunch and it no longer works. Nothing’s been changed other than a full stomach. There’s no rhyme or reason to working one minute and not the next, other than timing issues internal to the JTAG and/or possibly PIO.

If someone wants to work on fixing the paradigm with me I’ll gladly spend the time and effort in helping and providing any info necessary.

Here are some of the kinds of voodoo I’ve used to get debugging working:

  • Ground P0 on my ESP32 and press the reset button
  • Close down VSCode and restarting it
  • Pressing the reset button on the ESP32
  • Close down VSCode, pressing the reset button on the ESP32 and starting VSCode
  • Spinning clockwise in my chair
  • Doing a clean build of my code
  • Rebooting my Mac

I’m sure you get the point…


Hello solnd,

I had the identical problem with ESP32-Wrover-E and ESP-Prog.
I worked with it for weeks without problems and out of the sudden, the debugger does not work anymore.

Thank you so much indeed for your procedure!!
It works great and it is the ONLY WAY to debug bigger programs…

You saved my day !!

Awesome, glad to hear that it helped! If you want you can follow the bug here. Hopefully they can fix it some day.