--port-filter argument key not recognized. (ESPTOOL-1103)

[DoubleNom]

Operating System

windows

Esptool Version

5.0.1

Python Version

3.13.5

Chip Description

ESP32-C6

Device Description

ESP32-S3-DevKitC-1 and ESP32-C6 module

Hardware Configuration

N/A

How is Esptool Run

run from terminal

Full Esptool Command Line that Was Run

esptool --port-filter vid=0x303a read-mac

Esptool Output

esptool v5.0.1

A fatal error occurred: Option --port-filter argument key not recognized.

More Information

changing vid to 303a or 12346 produce the same output

Other Steps to Reproduce

Commands work properly when run with esptool 4.9 (using read_mac instead of read-mac)

I Have Read the Troubleshooting Guide

• I confirm I have read the troubleshooting guide.

[github-actions]

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

---

The error message “Option --port-filter argument key not recognized” occurs because the --port-filter option is not available in esptool v5.0.1. According to the Espressif documentation, the --port-filter option is documented for newer versions of esptool, but your command output shows you are using v5.0.1, which does not support this option yet. This is why you see the error, regardless of the argument you provide.

Solution:
To use the --port-filter option, you need to upgrade to a newer version of esptool that supports this feature. The documentation for ESP32-C6 confirms that --port-filter is a valid option, but only in more recent releases than v5.0.1. Please upgrade esptool to the latest version using pip:

pip install --upgrade esptool

After upgrading, your command should work as expected:

esptool --port-filter vid=0x303a read-mac

For reference, see the official documentation for --port-filter support: ESP32-C6 Esptool Advanced Options

[DoubleNom]

Replying to bot.
I am already using the latest version of esptool available on pip, and the --port-filter option appear in the help menu.

--port-filter           [TEXT]                                        Serial port device filter, can be vid=NUMBER,  │
│                                                                       pid=NUMBER, name=SUBSTRING, serial=SUBSTRING.