Web Serial / flashing isn't working
Flashing uses the browser's Web Serial API, which has requirements:
- Browser — use Chrome or Edge (Chromium). Firefox and Safari don't support Web Serial.
- Permission — you must pick the serial port in the browser prompt each session.
- USB — use a data-capable USB cable (not charge-only) and a direct port if possible.
- Drivers — some boards need a USB-UART driver (CP210x / CH340) installed at the OS level for the port to appear.
- Conflicts — close other serial monitors/IDEs holding the port.
- 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:
- 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,screenorminicom, and any other browser tab connected to the board, including another flasher or the serial monitor on synacl.com/flash. - Linux: your user may not use serial devices. Run
sudo usermod -aG dialout $USER(on Arch-based systems the group isuucp), then log out and back in. - 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.
- 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.