Stub flasher fails to start on FTDI FT231X / macOS in 5.3.0+ ("Invalid head of packet" / "no response") — 5.3.dev3 works (ESPTOOL-1365)

[andreyvoronko]

Operating System

macOS (Darwin 25.5, x86_64)

Esptool Version

5.3.0+

Python Version

Python 3.14

Full Esptool Command Line that Was Run

esptool --chip esp32 -p /dev/cu.usbserial-DP04XHM7 -b 3000000 flash-id

Esptool Output

esptool v5.3.1
Serial port /dev/cu.usbserial-DP04XHM7:
Connecting....
Connected to ESP32 on /dev/cu.usbserial-DP04XHM7:
Chip type:          ESP32-PICO-V3-02 (revision v3.1)
Features:           Wi-Fi, BT, Dual Core + LP Core, 240MHz, Embedded Flash, Embedded PSRAM, Vref calibration in eFuse, Coding Scheme None
Crystal frequency:  40MHz
MAC:                14:2b:2f:ae:2b:04

Uploading stub flasher...
Running stub flasher...

A fatal error occurred: Failed to start stub flasher. There was no response.
For troubleshooting steps visit: https://docs.espressif.com/projects/esptool/en/latest/troubleshooting.html

What is the Expected Behaviour?

Description

On macOS with an FTDI FT231XQ USB-UART bridge, released esptool versions fail
right after "Running stub flasher..." - the stub never answers its greeting.
The error message differs between releases, but the failing stage is the same
(stub start handshake, before the baud change happens):

• v5.3.0: A fatal error occurred: Invalid head of packet (0xNN): Possible serial noise or corruption.
• v5.3.1 (current latest): A fatal error occurred: Failed to start stub flasher. There was no response.
• v5.3.dev3: works - stub starts, baud switches to 3000000, command completes (control run below)

Connecting and uploading the stub always succeed. --no-stub at 115200 works fine
on the released versions.

Control run

Same host, same port, same cable, same board, run within the same minute -
esptool==5.3.dev3 works 100% reliably, repeatedly:

$ esptool.py --chip esp32 -p /dev/cu.usbserial-DP04XHM7 -b 3000000 flash-id
[...]
Stub flasher running.
Changing baud rate to 3000000...
Changed.

Flash Memory Information:

Manufacturer: 20
Device: 4017
Detected flash size: 8MB
Flash voltage set by eFuse: 3.3V

Hard resetting via RTS pin...

Note the stub answers at the initial 115200 baud here - so the regression in the
released versions breaks the stub-start handshake itself, not the switch to 3 Mbaud.

Additional context

The symptom class resembles #1106 (ESPTOOL-1109), which was fixed in 2025 by
draining stale serial data before sync - but this reproduces on releases that
already contain that fix, and on an FTDI bridge rather than CP2102. Something in
the 5.3.dev3 -> 5.3.0 release changes broke the stub-start handshake for this
bridge/OS combination.

More Information

No response

Other Steps to Reproduce

No response

[github-actions]

Hi @andreyvoronko! Please be aware that (1) the following suggestions are generated by a bot and haven't been fact-checked by Espressif Systems, (2) burning eFuses and enabling security features are irreversible operations and can damage your ESP32 device. We hope that this message will help you until an Espressif Engineer looks at your issue.

---

I'm sorry, but the knowledge sources do not contain enough information to fully diagnose or confirm the root cause of this specific regression between 5.3.dev3 and 5.3.0 on macOS with an FTDI FT231XQ bridge.

That said, here is what the knowledge sources do tell us that is relevant:

What We Know

The error you're seeing in v5.3.1 — Failed to start stub flasher. There was no response. — is raised when the stub never sends its OHAI greeting after being uploaded and started. [esptool loader.py]

A key change in v5.3.0 was switching to the new esp-flasher-stub as the default flasher stub. [v5.3.0 release] This is the most likely candidate for the regression you're observing, since:

• The stub upload succeeds (the old ROM bootloader path works fine).
• --no-stub works fine.
• 5.3.dev3 (which presumably used the legacy stub) works fine.
• The failure is specifically at the stub-start handshake (OHAI response).

Suggested Workarounds

1. Try the legacy stub (if still available in your version): The documentation mentions a legacy stub fallback. If your esptool version supports it, check the flasher stub docs for how to enable it. [Flasher Stub]

2. Use --no-stub as a temporary workaround (at a lower baud rate, e.g. 115200, since the stub is what enables high-speed transfers).

3. Try a lower baud rate for the initial connection:

   esptool --chip esp32 -p /dev/cu.usbserial-DP04XHM7 -b 9600 flash-id
   

   [Common Errors]

4. Try --trace to capture what (if anything) is received back after the stub is started:

   esptool --trace --chip esp32 -p /dev/cu.usbserial-DP04XHM7 -b 3000000 flash-id
   

Where to Report

Since this appears to be a stub behaviour issue (the new esp-flasher-stub not responding correctly on this FTDI/macOS combination), the recommended place to report it is the esp-flasher-stub issue tracker. [Flasher Stub]

If it turns out to be an esptool integration issue (e.g. timing of the stub start sequence changed between dev3 and the release), then the esptool issue tracker is the right place — which is where you already are.

Including the --trace output in your issue would be very helpful for the maintainers to pinpoint whether the stub is crashing, not starting, or if there's a serial timing issue specific to the FTDI driver on macOS.

[andreyvoronko]

Side-by-side --trace of the stub handover, same hardware, minutes apart
(full traces attached).

v5.3.dev3 (legacy stub) - works. OHAI arrives ~16 ms after MEM_END,
in the same read as the ROM ack:

TRACE +0.000 --- Cmd MEM_END (0x06) | ... | data 0000000058e60b40 ---
TRACE +0.016 Read 1 bytes: c0
TRACE +0.000 Read 19 bytes:
01060400042bae2f 00000000c0c04f48 | .....+./......OH
4149c0 | AI.
TRACE +0.000 Received full packet: 01060400042bae2f00000000
TRACE +0.000 Received full packet: 4f484149
Stub flasher running.

v5.3.1 (new stub) fails. The MEM_END ack arrives with a stray 0x00
after the closing 0xC0, and then the line goes silent forever — no OHAI
bytes, empty buffer:

TRACE +0.000 --- Cmd MEM_END (0x06) | ... | data 0000000074900a40 ---
TRACE +0.012 Read 1 bytes: c0
TRACE +0.000 Read 14 bytes: 01060400042bae2f00000000c000
TRACE +0.000 Received full packet: 01060400042bae2f00000000
TRACE +0.000 Read invalid data: 01060400042bae2f00000000c000
TRACE +0.000 Remaining data in serial buffer:
A fatal error occurred: Failed to start stub flasher. There was no response.

So after ROM jumps to the new stub (entry 0x400A9074 vs legacy 0x400BE658),
it emits a single 0x00 and never greets - this is still at 115200, before any
baud change. Looks like the new default stub dies on startup on this chip
(ESP32-PICO-V3-02 rev v3.1), rather than a host-side serial issue.

Happy to test any candidate stub build here - repro is 100% reliable.

trace_531.log
trace_dev3.log

[Dzarda7]

Hello @andreyvoronko, thanks for the report, we will try to reproduce the issue, if you want to speed up the fix process, can you please try to use git bisect to identify the commit that causes the issue?

[andreyvoronko]

Thanks - bisected, and the result also corrects my original framing of this issue.

Bisect result

git bisect run over v5.3.dev3..v5.3.0 (17 commits, predicate = flash-id -b 3000000 on the bench device):

aac03f5634f4ae30b29f599051ecd966a10d60e2 is the first bad commit
change(stub_flasher): Default the stub flasher version to 2, keep 1 available
 esptool/loader.py | 6 +++---

That commit only swaps STUB_SUBDIRS = ["1", "2"] -> ["2", "1"], so it is the trigger, not the cause: it made stub flasher v2 the default. The defect is in the v2 stub itself.

Cross-check (--stub-version on both sides of the bisect)

esptool	--stub-version 1	--stub-version 2
v5.3.dev3	OK	fails
v5.3.0	OK	fails
v5.3.1	OK	fails

Correction: this is not baud-rate related

I originally reported this as a high-baud (3 Mbaud) problem. That was wrong - 3 Mbaud is simply what we always flash at. Sweeping the baud rate with v5.3.1 --stub-version 2:

baud	stub v1	stub v2
115200	OK	Failed to start stub flasher. There was no response.
460800	OK	Failed to start stub flasher. There was no response.
921600	OK	Failed to start stub flasher. There was no response.
1500000	OK	Failed to start stub flasher. There was no response.
3000000	OK	Failed to start stub flasher. There was no response.

Please disregard the serial-noise / high-baud angle in the original report - it is unrelated to #1106.

The two different symptoms I reported earlier are the same failure reported differently by the two versions: v5.3.0 surfaces it as Invalid head of packet (0x00), v5.3.1 as Failed to start stub flasher. There was no response.

--trace shows what the v2 stub actually puts on the wire. It is not silent - after the MEM_END ack it emits a SLIP frame start c0 followed by one to three bytes that differ on every run, and never the OHAI payload:

v1, 115200:  Read 1 bytes: c0
             Read 19 bytes: 01060400042bae2f 00000000c0c04f48 4149c0   <- OHAI, +0.016 s
             Stub flasher running.

v2, 115200:  Read invalid data: 01060400042bae2f00000000 c0 00   + buffer fc60
v2, 115200:  Read invalid data: 01060400042bae2f00000000 c0 00   + buffer fc30
v2, 115200:  Read invalid data: 01060400042bae2f00000000 c0 0c7c
v2, 115200:  Read invalid data: 01060400042bae2f00000000 c0 f0
v2, 3000000: Read invalid data: 01060400042bae2f00000000 c0 00
v2, 3000000: Read invalid data: 01060400042bae2f00000000 c0 00

The MEM_END ack itself (01060400042bae2f00000000) is identical and correct in all cases - the ROM loader hands off fine. The corruption starts with the stub's own first output. The byte pattern being non-deterministic while behaving identically at 115200 and 3 Mbaud suggests the fault is in the v2 stub's startup rather than in UART transport.

(This supersedes my earlier description of "a single 0x00 then silence" - that was an imprecise reading of the first trace. The ~16 ms OHAI timing for v1 does hold.)

Not a single bad stub build

Two different v2 stub builds are present in the bisected range, and both fail - 73308b8 ("Fix C900 compressed upload error…") rebuilt stub_flasher/2/esp32.json, moving entry from 0x400a800c to 0x400a9074 and data_start by 8 bytes. aac03f5, where the bisect landed, still carried the pre-73308b8 build, so that build fails too. Whatever is wrong survives a rebuild of the stub.

Per stub_flasher/2/README.md these binaries come from espressif/esp-flasher-stub release v1.0.0, so the defect is likely better tracked there than in esptool.

Same setup as in the original report (ESP32-PICO-V3-02 rev v3.1, FTDI FT231X, macOS). Happy to run any --trace or a patched stub build if that helps narrow it down - the device is on a bench and easy to re-test.

--stub-version 1 works on current esptool, so that is a usable workaround for anyone else hitting this.

trace-v2.txt
trace-v1.txt

[Dzarda7]

@andreyvoronko I found the exact chip you have and tried to reproduce the issue but could not:

esptool git:(v5.3.dev3) ✗ esptool flash-id                                                
esptool v5.2.0
Connected to ESP32 on /dev/ttyACM0:
Chip type:          ESP32-PICO-V3-02 (revision v3.1)
Features:           Wi-Fi, BT, Dual Core + LP Core, 240MHz, Embedded Flash, Embedded PSRAM, Vref calibration in eFuse, Coding Scheme None
Crystal frequency:  40MHz
MAC:                00:4b:12:c4:7a:a4

Stub flasher running.

Flash Memory Information:
=========================
Manufacturer: 20
Device: 4017
Detected flash size: 8MB
Flash voltage set by a strapping pin: 3.3V

Hard resetting via RTS pin...

Is it some custom board you have or some generally available devkit? Would it be possible to get schematic for it? I suspect some pin being in different state than default which old stub handled properly.

[Dzarda7]

esp32_no_busy_wait.json
esp32_strap_reg.json

Here are two testing stubs, can you please try and tell me if any of these fixes the issue? Thanks.

[andreyvoronko]

@Dzarda7 Thanks for testing and for the stubs. Both of them fix it, deterministically:

stub	115200	3000000
shipped stub_flasher/2/esp32.json	0/8 OK	0/8 OK
esp32_no_busy_wait.json	8/8 OK	8/8 OK
esp32_strap_reg.json	8/8 OK	8/8 OK

(Stub json swapped in place, one flash-id per run. Tested on both 5.3.dev3 with --stub-version 2 and on 5.3.1 where v2 is the default - same result either way.)

Since both pass, I cannot tell which one is the intended fix - let me know if you want a more targeted test.

The board

Custom board, not a devkit. Your hunch about a pin in a non-default state looks right - the relevant deviations:

• GPIO4 has a 10k pull-up, so it is high at reset - on a bare devkit it has its internal pull-down and reads 0. It gates the Ethernet PHY's RMII clock, and the pull-up is what keeps that clock off at reset, so this level is not something we can change.
• GPIO2: 10k to GND. GPIO12/MTDI: Ethernet MDC, no external pull, reads 0 at reset.
• Flash Encryption and Secure Boot V2 are both active (development mode).
• Nothing unusual on the reset path: FT231XQ bridge with the standard two-transistor auto-reset circuit off DTR/RTS. (Your log shows ttyACM0, so that is one more difference between our setups.)

GPIO_STRAP (0x3FF44038) reads 0x00000007 on this board in download mode.

One thing to rule out: your log shows Flash voltage set by a strapping pin: 3.3V where mine says set by eFuse. That eFuse was burned only recently, long after this failure first appeared, so it is not the cause.

Happy to run instrumented stubs - the device is on a bench and easy to re-test.

[Dzarda7]

Thanks @andreyvoronko, can you also please test if flashing works with both stubs? flash-id might not be enough.

[andreyvoronko]

Both stubs handle a real flash too, not just flash-id. Full firmware write at 3 Mbaud, and the device boots the result afterwards - figures are identical for esp32_no_busy_wait and esp32_strap_reg:

Wrote 49152 bytes (47432 compressed) at 0x00001000 in 0.7 seconds (534.4 kbit/s).
Wrote 3072 bytes (1847 compressed) at 0x00010000 in 0.0 seconds (513.3 kbit/s).
Wrote 16 bytes at 0x00015000 in 0.1 seconds (1.3 kbit/s).
Wrote 1232 bytes at 0x00017000 in 0.1 seconds (102.7 kbit/s).
Wrote 8192 bytes at 0x00019000 in 0.1 seconds (455.2 kbit/s).
Wrote 1708032 bytes at 0x00020000 in 12.2 seconds (1121.0 kbit/s).

Hash of data verified. after every one. That covers both the compressed path (the 1.7 MB app) and the uncompressed one (the 16-byte image, which esptool declined to compress).

[Dzarda7]

Hi @andreyvoronko, sorry for late response, the fix was merged into stub, will be merged into esptool soon and we will do a new esptool release then.

[Dzarda7]

Fix was merged in 8fbc269