arduino/Arduino · error · SerialException

Error touching serial port ''{0}''.

Error message

Error touching serial port ''{0}''.

What it means

Serial.touchForCDCReset throws SerialException when the 1200-baud DTR toggle used to reset a native-USB (CDC) board fails at the jSSC level. This touch procedure opens the port at 1200 baud, clears DTR, and closes it to reboot the board into bootloader mode; any SerialPortException during that sequence is wrapped in this message.

Source

Thrown at arduino-core/src/processing/app/Serial.java:107

  public Serial(String iname) throws SerialException {
    this(iname, PreferencesData.getInteger("serial.debug_rate", 9600),
      PreferencesData.getNonEmpty("serial.parity", "N").charAt(0),
      PreferencesData.getInteger("serial.databits", 8),
      PreferencesData.getFloat("serial.stopbits", 1),
      !BaseNoGui.getBoardPreferences().getBoolean("serial.disableRTS"),
      !BaseNoGui.getBoardPreferences().getBoolean("serial.disableDTR"));
  }

  public static boolean touchForCDCReset(String iname) throws SerialException {
    SerialPort serialPort = new SerialPort(iname);
    try {
      serialPort.openPort();
      serialPort.setParams(1200, 8, SerialPort.STOPBITS_1, SerialPort.PARITY_NONE);
      serialPort.setDTR(false);
      serialPort.closePort();
      return true;
    } catch (SerialPortException e) {
      throw new SerialException(format(tr("Error touching serial port ''{0}''."), iname), e);
    } finally {
      if (serialPort.isOpened()) {
        try {
          serialPort.closePort();
        } catch (SerialPortException e) {
          // noop
        }
      }
    }
  }

  protected Serial(String iname, int irate, char iparity, int idatabits, float istopbits, boolean setRTS, boolean setDTR) throws SerialException {
    //if (port != null) port.close();
    //this.parent = parent;
    //parent.attach(this);

    resetDecoding(StandardCharsets.UTF_8);

View on GitHub (pinned to a0df6e0e83)

Solutions

1. Close any other application using the port (Serial Monitor, screen, minicom) and disable brltty/modemmanager on Linux, then retry the upload
2. Add your user to the dialout group (sudo usermod -aG dialout $USER) and re-login to fix permission-denied cases
3. Reconnect the board / try another USB cable and port, confirming the port name still exists in the Tools menu
4. Update USB/serial drivers (Windows) or jSSC-related firmware issues; retry the upload

Example fix

// before: port held by another process
Runtime.getRuntime().exec("screen /dev/ttyACM0 9600");
// after: nothing else owns the port
// sudo systemctl stop ModemManager; usermod -aG dialout $USER
upload(portName); // touchForCDCReset now succeeds

SerialPort p = new SerialPort(portName);
if (!p.isOpened()) {
  // check device node exists and nothing else holds it before touching
  if (!new File(portName).exists()) throw new IllegalStateException("Port missing: " + portName);
}

try {
  Serial.touchForCDCReset(portName);
} catch (SerialException e) {
  if (e.getMessage().contains("Error touching serial port")) {
    // close other monitors, fix permissions, replug board, retry upload
  } else throw e;
}

When it happens

Trigger: touchForCDCReset() is called before uploading to a CDC board; serialPort.openPort(), setParams(1200,...), setDTR(false), or closePort() throws SerialPortException (port busy, permission denied, device disconnected).

Common situations: Another program (serial monitor, screen, modemmanager) holds the port; user lacks dialout/uucp group membership; the board was unplugged or re-enumerated mid-touch; buggy USB drivers on Windows.

Related errors

• Couldn't find a Board on the selected port. Check that you h
• serial.port
• SCP error:
• Uknown SCP error:
• Burning bootloader is not supported via network!

AI-assisted analysis of arduino/Arduino@a0df6e0e83 (2026-09-06). Data as JSON: /api/errors/feb8d5929d13922a. Report an issue: GitHub.