{"record":{"id":"57e61b5910e9108e","repo":"arduino/Arduino","slug":"error-opening-serial-port-0-try-consulting","errorCode":null,"errorMessage":"Error opening serial port ''{0}''. Try consulting the documentation at http://playground.arduino.cc/Linux/All#Permission","messagePattern":"Error opening serial port ''(.+?)''\\. Try consulting the documentation at http://playground\\.arduino\\.cc/Linux/All#Permission","errorType":"exception","errorClass":"SerialException","httpStatus":null,"severity":"error","filePath":"arduino-core/src/processing/app/Serial.java","lineNumber":150,"sourceCode":"    if (istopbits == 2) stopbits = SerialPort.STOPBITS_2;\n\n    // 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","sourceCodeStart":132,"sourceCodeEnd":168,"githubUrl":"https://github.com/arduino/Arduino/blob/a0df6e0e83b652c72bc78b0a1376c54d6ebc3bee/arduino-core/src/processing/app/Serial.java#L132-L168","documentation":"The Serial constructor throws this SerialException when opening the port fails with TYPE_PERMISSION_DENIED on a /dev* port. The message specifically points Linux users to the Arduino permission documentation because it almost always means the user is not allowed to access the serial device.","triggerScenarios":"new Serial(...) calls port.openPort(); jSSC returns SerialPortException with exception type TYPE_PERMISSION_DENIED and port name starting with \"/dev\" (Linux/macOS), e.g. /dev/ttyUSB0 or /dev/ttyACM0.","commonSituations":"User not in dialout/uucp group on Linux; modemmanager or brltty grabbing the device; device node with unusual permissions; macOS inaccessible /dev/cu.* device.","solutions":["Add your user to the dialout group and re-login: sudo usermod -aG dialout $USER (or uucp on Arch), then verify with `groups`","Check device permissions (ls -l /dev/ttyACM0) and stop conflicting services: sudo systemctl stop ModemManager brltty","Use a udev rule to grant stable access to the device, then replug the board","Run once with sudo to confirm it is purely a permission problem, then fix group membership rather than always using sudo"],"exampleFix":"// before: permission denied on /dev/ttyACM0\n// after (system fix, then restart session)\n// sudo usermod -aG dialout $USER && newgrp dialout\nSerial serial = new Serial(portName, 9600, 'N', 8, 1);","handlingStrategy":"validation","validationCode":"File dev = new File(portName);\nif (!dev.exists()) throw new IllegalStateException(\"No such port: \" + portName);\ntry (var ch = new java.io.RandomAccessFile(dev, \"rw\").getChannel()) {\n  // opening rw succeeds only with permission\n} catch (java.io.IOException e) {\n  throw new IllegalStateException(\"No permission on \" + portName + \": add user to dialout\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  Serial serial = new Serial(portName, 9600, 'N', 8, 1);\n} catch (SerialException e) {\n  if (e.getMessage().contains(\"Permission\")) {\n    System.err.println(\"Add yourself to dialout and re-login, then retry.\");\n  } else throw e;\n}","preventionTips":["Join the dialout (or uucp) group and re-login after installing the IDE","Disable ModemManager/brltty which hijack /dev/ttyACM*/ttyUSB* devices","Use a udev rule for persistent device permissions","Verify access with `ls -l /dev/tty*` and a quick `minicom` test before debugging the app"],"tags":["serial","permission","linux","dialout"],"backgroundTag":"permission-denied","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"}