arduino/Arduino · error · SerialException

Error opening serial port

Error message

Error opening serial port ''{0}''. Try consulting the documentation at http://playground.arduino.cc/Linux/All#Permission

What it means

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.

Solutions

1. Add your user to the dialout group and re-login: sudo usermod -aG dialout $USER (or uucp on Arch), then verify with `groups`
2. Check device permissions (ls -l /dev/ttyACM0) and stop conflicting services: sudo systemctl stop ModemManager brltty
3. Use a udev rule to grant stable access to the device, then replug the board
4. Run once with sudo to confirm it is purely a permission problem, then fix group membership rather than always using sudo

Example fix

// before: permission denied on /dev/ttyACM0
// after (system fix, then restart session)
// sudo usermod -aG dialout $USER && newgrp dialout
Serial serial = new Serial(portName, 9600, 'N', 8, 1);

File dev = new File(portName);
if (!dev.exists()) throw new IllegalStateException("No such port: " + portName);
try (var ch = new java.io.RandomAccessFile(dev, "rw").getChannel()) {
  // opening rw succeeds only with permission
} catch (java.io.IOException e) {
  throw new IllegalStateException("No permission on " + portName + ": add user to dialout");
}

try {
  Serial serial = new Serial(portName, 9600, 'N', 8, 1);
} catch (SerialException e) {
  if (e.getMessage().contains("Permission")) {
    System.err.println("Add yourself to dialout and re-login, then retry.");
  } else throw e;
}

When it happens

Trigger: 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.

Common situations: User not in dialout/uucp group on Linux; modemmanager or brltty grabbing the device; device node with unusual permissions; macOS inaccessible /dev/cu.* device.

Understand the failure class

Background: Permission denied / not authorized / 403 Forbidden: access-control rejections when the caller lacks the required role, grant, or ownership — this error's family across 18 libraries.

Related errors

• Could not remove old version of
• Couldn't find a Board on the selected port. Check that you…
• Error opening serial port
• Error touching serial port
• serial.port

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

Appendix: source

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

    if (istopbits == 2) stopbits = SerialPort.STOPBITS_2;

    // This is required for unit-testing
    if (iname.equals("none")) {
      return;
    }

    try {
      port = new SerialPort(iname);
      port.openPort();
      boolean res = port.setParams(irate, idatabits, stopbits, parity, setRTS, setDTR);
      if (!res) {
        System.err.println(format(tr("Error while setting serial port parameters: {0} {1} {2} {3}"),
                                  irate, iparity, idatabits, istopbits));
      }
      port.addEventListener(this);
    } catch (SerialPortException e) {
      if (e.getPortName().startsWith("/dev") && SerialPortException.TYPE_PERMISSION_DENIED.equals(e.getExceptionType())) {
        throw new SerialException(format(tr("Error opening serial port ''{0}''. Try consulting the documentation at http://playground.arduino.cc/Linux/All#Permission"), iname));
      }
      throw new SerialException(format(tr("Error opening serial port ''{0}''."), iname), e);
    }

    if (port == null) {
      throw new SerialNotFoundException(format(tr("Serial port ''{0}'' not found. Did you select the right one from the Tools > Serial Port menu?"), iname));
    }
  }

  public void setup() {
    //parent.registerCall(this, DISPOSE);
  }

  public void dispose() throws IOException {
    if (port != null) {
      try {
        if (port.isOpened()) {
          port.closePort();  // close the port

View on GitHub (pinned to a0df6e0e83)