arduino/Arduino · error · SerialNotFoundException

serial.port

Error message

serial.port

What it means

runCommand expands upload/bootloader command patterns using preference values. If a pattern references 'serial.port' and that preference is missing, PreferencesMap.getOrExcept throws a PreferencesMapException whose message is the raw key 'serial.port'. runCommand catches it and rethrows as SerialNotFoundException because uploading without a selected serial port is meaningless. The 'message' is literally the missing preference key, not a human-readable error.

Source

Thrown at arduino-core/src/cc/arduino/packages/uploaders/SerialUploader.java:388

    new LoadVIDPIDSpecificPreferences().load(prefs);

    if (!runCommand("erase.pattern", prefs))
      return false;

    return runCommand("bootloader.pattern", prefs);
  }

  private boolean runCommand(String patternKey, PreferencesMap prefs) throws Exception, RunnerException {
    try {
      String pattern = prefs.getOrExcept(patternKey);
      StringReplacer.checkIfRequiredKeyIsMissingOrExcept("serial.port", pattern, prefs);
      String[] cmd = StringReplacer.formatAndSplit(pattern, prefs);
      return executeUploadCommand(cmd);
    } catch (RunnerException e) {
      throw e;
    } catch (PreferencesMapException e) {
      if (e.getMessage().equals("serial.port")) {
        throw new SerialNotFoundException(e);
      }
      throw e;
    } catch (Exception e) {
      throw new RunnerException(e);
    }
  }
}

View on GitHub (pinned to a0df6e0e83)

Solutions

1. Select the correct serial port via Tools->Port in the IDE before uploading
2. Programmatically set the port: PreferencesData.set("serial.port", "/dev/ttyUSB0") (or COM port on Windows)
3. Catch SerialNotFoundException and prompt the user to connect/select a board; refresh the port list after plugging in the device
4. Verify OS drivers for the board's USB-serial chip (CH340, FTDI, etc.) are installed so the port appears

Example fix

// before
uploader.uploadUsingPreferences(buildPath, className, true);
// after
if (PreferencesData.get("serial.port") == null || PreferencesData.get("serial.port").isEmpty()) {
  throw new IllegalArgumentException("Select a serial port before uploading");
}
uploader.uploadUsingPreferences(buildPath, className, true);

String port = PreferencesData.get("serial.port");
if (port == null || port.isEmpty()) throw new IllegalStateException("No serial port selected; choose one via Tools->Port");

try { uploader.uploadUsingPreferences(buildPath, className, true); } catch (SerialNotFoundException e) { refreshPortListAndPrompt(); }

When it happens

Trigger: Running uploadUsingPreferences, uploadUsingProgrammer, or burnBootloader when no serial port is selected (empty/missing 'serial.port' preference) while the upload pattern requires {serial.port}.

Common situations: No board connected and no port chosen in Tools->Port; headless/CLI invocation with default preferences; USB device unplugged or driver not loaded so the port was never registered.

Understand the failure class

Background: "missing required config value" errors: why libraries refuse to start when a configuration key is empty, unset, or blank — this error's family across 48 libraries.

Related errors

• Couldn't find a Board on the selected port. Check that you h
• Please select a programmer from Tools->Programmer menu
• Error touching serial port ''{0}''.
• Board is not selected
• Unable to understand proxy settings

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