UnsupportedCommandError when trying to flash on a board with Secure Download Mode (ESPTOOL-1346)

[niketic95]

Operating System

Ubuntu 22.04

Esptool Version

v5.3.0-14-g65f72ed

Python Version

Python 3.10.12

Full Esptool Command Line that Was Run

./esptool.py --chip esp32s3 --port /dev/ttyACM0 --no-stub write-flash -fm dio -ff 80m -fs 8MB 0x10000 hello_world.bin

Esptool Output

Warning: DEPRECATED: 'esptool.py' is deprecated. Please use 'esptool' instead. The '.py' suffix will be removed in a future major release.
esptool v5.3.0
Serial port /dev/ttyACM0:
Connecting...
Traceback (most recent call last):
  File "/home/stenic/Downloads/esptool/./esptool.py", line 37, in <module>
    esptool._main()
  File "/home/stenic/Downloads/esptool/esptool/__init__.py", line 1363, in _main
    main()
  File "/home/stenic/Downloads/esptool/esptool/__init__.py", line 1257, in main
    cli(args=args, esp=esp)
  File "/home/stenic/Downloads/esptool/esptool/cli_util.py", line 346, in __call__
    return super().__call__(*args, **kwargs)
  File "/home/stenic/.espressif/python_env/idf6.1_py3.10_env/lib/python3.10/site-packages/rich_click/rich_command.py", line 402, in __call__
    return super().__call__(*args, **kwargs)
  File "/home/stenic/.espressif/python_env/idf6.1_py3.10_env/lib/python3.10/site-packages/click/core.py", line 1524, in __call__
    return self.main(*args, **kwargs)
  File "/home/stenic/.espressif/python_env/idf6.1_py3.10_env/lib/python3.10/site-packages/rich_click/rich_command.py", line 216, in main
    rv = self.invoke(ctx)
  File "/home/stenic/.espressif/python_env/idf6.1_py3.10_env/lib/python3.10/site-packages/click/core.py", line 1912, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/home/stenic/.espressif/python_env/idf6.1_py3.10_env/lib/python3.10/site-packages/click/core.py", line 1308, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/home/stenic/.espressif/python_env/idf6.1_py3.10_env/lib/python3.10/site-packages/click/core.py", line 877, in invoke
    return callback(*args, **kwargs)
  File "/home/stenic/.espressif/python_env/idf6.1_py3.10_env/lib/python3.10/site-packages/click/decorators.py", line 34, in new_func
    return f(get_current_context(), *args, **kwargs)
  File "/home/stenic/Downloads/esptool/esptool/__init__.py", line 822, in write_flash_cli
    prepare_esp_object(ctx)
  File "/home/stenic/Downloads/esptool/esptool/__init__.py", line 542, in prepare_esp_object
    esp = esp or get_default_connected_device(
  File "/home/stenic/Downloads/esptool/esptool/__init__.py", line 1348, in get_default_connected_device
    _esp.connect(before, connect_attempts)
  File "/home/stenic/Downloads/esptool/esptool/loader.py", line 983, in connect
    self._post_connect()
  File "/home/stenic/Downloads/esptool/esptool/targets/esp32s3.py", line 332, in _post_connect
    self.disable_watchdogs()
  File "/home/stenic/Downloads/esptool/esptool/targets/esp32s3.py", line 315, in disable_watchdogs
    self.write_reg(self.RTC_CNTL_WDTWPROTECT_REG, self.RTC_CNTL_WDT_WKEY)
  File "/home/stenic/Downloads/esptool/esptool/loader.py", line 1008, in write_reg
    return self.check_command(
  File "/home/stenic/Downloads/esptool/esptool/loader.py", line 658, in check_command
    val, data = self.command(op, data, chk, timeout=timeout)
  File "/home/stenic/Downloads/esptool/esptool/loader.py", line 628, in command
    raise UnsupportedCommandError(self, op)
esptool.util.UnsupportedCommandError: This command (0x9) is not supported in Secure Download Mode

What is the Expected Behaviour?

• The binary to be flashed on address 0x10000

More Information

• Tested with the release of the tool, with the same behavior.
• Tested with the previous version of the tool v4.10.0 where I was able to flash.

Other Steps to Reproduce

No response

[github-actions]

Hi @niketic95! 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.

---

UnsupportedCommandError in Secure Download Mode

The error you're seeing is expected behavior — your ESP32-S3 has Secure Download Mode enabled, which restricts the available serial protocol commands. Specifically, writing registers (command 0x9) is not permitted in this mode. [Serial Protocol SDM]

Why it worked before

This is a regression introduced in a newer version of esptool. The tool now attempts to disable watchdogs (via write_reg) during connection, which is blocked in Secure Download Mode. Older versions (like v4.10.0) did not perform this step, so flashing worked.

What commands are supported in Secure Download Mode

Only the following esptool commands work when Secure Download Mode is active: [Basic Commands SDM]

• write-flash
• erase-region (but not erase-flash)
• get_security_info

Your write-flash command should be supported — the issue is that the connection setup itself fails before the actual flash write begins.

Known limitations to be aware of

Even once the connection issue is resolved, note these constraints: [SDM Limitations]

• The ROM bootloader defaults to a 2MB flash size in Secure Download Mode. Since you're targeting an 8MB flash, you must explicitly pass --flash-size 8MB (which you already are — good).
• Flash regions larger than 16MB cannot be accessed.
• The flasher stub cannot be used, so make sure --no-stub is included (which you already have).

Recommended action

Since this appears to be a regression in newer esptool versions, please report it directly on the esptool GitHub issue tracker with the details you've already gathered. The fix would need to be in the _post_connect / disable_watchdogs logic to skip register writes when Secure Download Mode is detected.

As a temporary workaround, you could try using esptool v4.10.0, which you confirmed works for your use case.

[radimkarnis]

Hi @niketic95,
thank you for the report, we are aware of the bug and will fix it ASAP.