{"record":{"id":"feb8d5929d13922a","repo":"arduino/Arduino","slug":"error-touching-serial-port-0","errorCode":null,"errorMessage":"Error touching serial port ''{0}''.","messagePattern":"Error touching serial port ''(.+?)''\\.","errorType":"exception","errorClass":"SerialException","httpStatus":null,"severity":"error","filePath":"arduino-core/src/processing/app/Serial.java","lineNumber":107,"sourceCode":"  public Serial(String iname) throws SerialException {\n    this(iname, PreferencesData.getInteger(\"serial.debug_rate\", 9600),\n      PreferencesData.getNonEmpty(\"serial.parity\", \"N\").charAt(0),\n      PreferencesData.getInteger(\"serial.databits\", 8),\n      PreferencesData.getFloat(\"serial.stopbits\", 1),\n      !BaseNoGui.getBoardPreferences().getBoolean(\"serial.disableRTS\"),\n      !BaseNoGui.getBoardPreferences().getBoolean(\"serial.disableDTR\"));\n  }\n\n  public static boolean touchForCDCReset(String iname) throws SerialException {\n    SerialPort serialPort = new SerialPort(iname);\n    try {\n      serialPort.openPort();\n      serialPort.setParams(1200, 8, SerialPort.STOPBITS_1, SerialPort.PARITY_NONE);\n      serialPort.setDTR(false);\n      serialPort.closePort();\n      return true;\n    } catch (SerialPortException e) {\n      throw new SerialException(format(tr(\"Error touching serial port ''{0}''.\"), iname), e);\n    } finally {\n      if (serialPort.isOpened()) {\n        try {\n          serialPort.closePort();\n        } catch (SerialPortException e) {\n          // noop\n        }\n      }\n    }\n  }\n\n  protected Serial(String iname, int irate, char iparity, int idatabits, float istopbits, boolean setRTS, boolean setDTR) throws SerialException {\n    //if (port != null) port.close();\n    //this.parent = parent;\n    //parent.attach(this);\n\n    resetDecoding(StandardCharsets.UTF_8);\n","sourceCodeStart":89,"sourceCodeEnd":125,"githubUrl":"https://github.com/arduino/Arduino/blob/a0df6e0e83b652c72bc78b0a1376c54d6ebc3bee/arduino-core/src/processing/app/Serial.java#L89-L125","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Close any other application using the port (Serial Monitor, screen, minicom) and disable brltty/modemmanager on Linux, then retry the upload","Add your user to the dialout group (sudo usermod -aG dialout $USER) and re-login to fix permission-denied cases","Reconnect the board / try another USB cable and port, confirming the port name still exists in the Tools menu","Update USB/serial drivers (Windows) or jSSC-related firmware issues; retry the upload"],"exampleFix":"// before: port held by another process\nRuntime.getRuntime().exec(\"screen /dev/ttyACM0 9600\");\n// after: nothing else owns the port\n// sudo systemctl stop ModemManager; usermod -aG dialout $USER\nupload(portName); // touchForCDCReset now succeeds","handlingStrategy":"try-catch","validationCode":"SerialPort p = new SerialPort(portName);\nif (!p.isOpened()) {\n  // check device node exists and nothing else holds it before touching\n  if (!new File(portName).exists()) throw new IllegalStateException(\"Port missing: \" + portName);\n}","typeGuard":null,"tryCatchPattern":"try {\n  Serial.touchForCDCReset(portName);\n} catch (SerialException e) {\n  if (e.getMessage().contains(\"Error touching serial port\")) {\n    // close other monitors, fix permissions, replug board, retry upload\n  } else throw e;\n}","preventionTips":["Close the Serial Monitor and terminal programs before uploading","Stop ModemManager/brltty on Linux; add user to dialout","Use a good USB cable and avoid hubs that re-enumerate boards","Confirm the port still exists in Tools > Serial Port before upload"],"tags":["serial","upload","cdc-reset","hardware"],"backgroundTag":"serial-port-error","analyzedSha":"a0df6e0e83b652c72bc78b0a1376c54d6ebc3bee","analyzedAt":"2026-09-06T10:13:38.901Z","contentChangedAt":"2026-09-06T10:13:38.901Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}