{"record":{"id":"0baf94be3c4da7bb","repo":"arduino/Arduino","slug":"error-opening-serial-port-0","errorCode":null,"errorMessage":"Error opening serial port ''{0}''.","messagePattern":"Error opening serial port ''(.+?)''\\.","errorType":"exception","errorClass":"SerialException","httpStatus":null,"severity":"error","filePath":"arduino-core/src/processing/app/Serial.java","lineNumber":152,"sourceCode":"    // This is required for unit-testing\n    if (iname.equals(\"none\")) {\n      return;\n    }\n\n    try {\n      port = new SerialPort(iname);\n      port.openPort();\n      boolean res = port.setParams(irate, idatabits, stopbits, parity, setRTS, setDTR);\n      if (!res) {\n        System.err.println(format(tr(\"Error while setting serial port parameters: {0} {1} {2} {3}\"),\n                                  irate, iparity, idatabits, istopbits));\n      }\n      port.addEventListener(this);\n    } catch (SerialPortException e) {\n      if (e.getPortName().startsWith(\"/dev\") && SerialPortException.TYPE_PERMISSION_DENIED.equals(e.getExceptionType())) {\n        throw new SerialException(format(tr(\"Error opening serial port ''{0}''. Try consulting the documentation at http://playground.arduino.cc/Linux/All#Permission\"), iname));\n      }\n      throw new SerialException(format(tr(\"Error opening serial port ''{0}''.\"), iname), e);\n    }\n\n    if (port == null) {\n      throw new SerialNotFoundException(format(tr(\"Serial port ''{0}'' not found. Did you select the right one from the Tools > Serial Port menu?\"), iname));\n    }\n  }\n\n  public void setup() {\n    //parent.registerCall(this, DISPOSE);\n  }\n\n  public void dispose() throws IOException {\n    if (port != null) {\n      try {\n        if (port.isOpened()) {\n          port.closePort();  // close the port\n        }\n      } catch (SerialPortException e) {","sourceCodeStart":134,"sourceCodeEnd":170,"githubUrl":"https://github.com/arduino/Arduino/blob/a0df6e0e83b652c72bc78b0a1376c54d6ebc3bee/arduino-core/src/processing/app/Serial.java#L134-L170","documentation":"Thrown by the Serial constructor in arduino-core when jSSC fails to open the requested serial port. It wraps the underlying SerialPortException and indicates the OS refused or failed the port open. The message includes the port name; a special variant with a documentation link is used for Linux permission failures.","triggerScenarios":"Calling new Serial() / Serial.open with a port name that the OS cannot open: port busy (already opened elsewhere), device disconnected, driver missing, or (on Linux, /dev/tty* paths) permission denied handled by the sibling message.","commonSituations":"Serial Monitor already holding the port; Arduino unplugged or re-enumerated with a different COM number; user not in dialout/uucp group on Linux; bogus or empty port string.","solutions":["Close any other program using the port (Serial Monitor, screen, another IDE instance)","Verify the device is connected and the port name matches (Tools > Serial Port)","On Linux add your user to the dialout group or install the udev rules","Reconnect/replug the board and retry","Catch SerialException and show the wrapped cause for diagnosis"],"exampleFix":"// before\nSerial serial = new Serial();\nserial.open(\"/dev/ttyUSB0\");\n// after\ntry {\n  Serial serial = new Serial();\n  serial.open(\"/dev/ttyUSB0\");\n} catch (SerialException e) {\n  System.err.println(\"Port open failed: \" + e.getMessage());\n}","handlingStrategy":"try-catch","validationCode":"boolean canOpen = Arrays.asList(Serial.list()).contains(iname);\nif (!canOpen) throw new IllegalStateException(\"Port not listed: \" + iname);","typeGuard":"static boolean portAvailable(String name) {\n  return name != null && !name.isEmpty() && Arrays.asList(Serial.list()).contains(name);\n}","tryCatchPattern":"try {\n  serialPort = new Serial(iname);\n} catch (SerialException e) {\n  // e.getCause() is the underlying SerialPortException: check its type\n  System.err.println(\"Open failed for \" + iname + \": \" + e.getCause());\n}","preventionTips":["Close the Serial Monitor and other port users before opening","Call Serial.list() and verify the port exists before opening","On Linux, ensure the user is in the dialout group and udev rules are installed","Handle replug/re-enumeration by refreshing the port name"],"tags":["serial","io","arduino"],"backgroundTag":"file-open-failed","analyzedSha":"a0df6e0e83b652c72bc78b0a1376c54d6ebc3bee","analyzedAt":"2026-09-06T10:13:38.901Z","contentChangedAt":"2026-09-06T10:13:38.901Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}