Web Serial / flashing isn't working

Updated

Flashing uses the browser's Web Serial API, which has requirements:

  1. Browser — use Chrome or Edge (Chromium). Firefox and Safari don't support Web Serial.
  2. Permission — you must pick the serial port in the browser prompt each session.
  3. USB — use a data-capable USB cable (not charge-only) and a direct port if possible.
  4. Drivers — some boards need a USB-UART driver (CP210x / CH340) installed at the OS level for the port to appear.
  5. Conflicts — close other serial monitors/IDEs holding the port.
  6. Linux — Chrome lists the port but can't open it until your user may use serial devices. Run sudo usermod -aG dialout $USER, log out and back in, then click Connect again.

If Chrome's port picker says No compatible devices found, the computer sees no serial port at all: check the cable (3) and the driver (4) first. Boards with native USB (ESP32-S2, S3, C3, C6) need no driver, but may need the BOOT button held while you plug them in.

"Failed to open serial port"

If the flasher's log shows

Failed to execute 'open' on 'SerialPort': Failed to open serial port.

Chrome found the port and you picked it, but the operating system wouldn't let Chrome open it. Work through these in order, clicking Connect again after each:

  1. Something else has the port open. Only one program can use a serial port at a time. Close the Arduino IDE or PlatformIO serial monitor, any terminal running esptool, screen or minicom, and any other browser tab connected to the board, including another flasher or the serial monitor on synacl.com/flash.
  2. Linux: your user may not use serial devices. Run sudo usermod -aG dialout $USER (on Arch-based systems the group is uucp), then log out and back in.
  3. The port is stale. Unplug the board, wait a few seconds and plug it back in, then pick the port again. On Windows this also frees a COM port left locked by a program that crashed.
  4. The board keeps resetting. On boards with native USB (USB ID 303A:1001: ESP32-S3, C3, C6 and similar), the port drops off and comes back whenever the chip resets or the running firmware takes over the USB pins, so Chrome can list a port it can no longer open. Put the board in download mode first: hold BOOT, press and release RESET (or plug it in with BOOT held), release BOOT, then pick the port again.

Once the port appears and is selected, flashing proceeds.