{"record":{"id":"dd081228d9cefda4","repo":"arduino/Arduino","slug":"serial-port","errorCode":null,"errorMessage":"serial.port","messagePattern":"serial\\.port","errorType":"exception","errorClass":"SerialNotFoundException","httpStatus":null,"severity":"error","filePath":"arduino-core/src/cc/arduino/packages/uploaders/SerialUploader.java","lineNumber":388,"sourceCode":"    new LoadVIDPIDSpecificPreferences().load(prefs);\n\n    if (!runCommand(\"erase.pattern\", prefs))\n      return false;\n\n    return runCommand(\"bootloader.pattern\", prefs);\n  }\n\n  private boolean runCommand(String patternKey, PreferencesMap prefs) throws Exception, RunnerException {\n    try {\n      String pattern = prefs.getOrExcept(patternKey);\n      StringReplacer.checkIfRequiredKeyIsMissingOrExcept(\"serial.port\", pattern, prefs);\n      String[] cmd = StringReplacer.formatAndSplit(pattern, prefs);\n      return executeUploadCommand(cmd);\n    } catch (RunnerException e) {\n      throw e;\n    } catch (PreferencesMapException e) {\n      if (e.getMessage().equals(\"serial.port\")) {\n        throw new SerialNotFoundException(e);\n      }\n      throw e;\n    } catch (Exception e) {\n      throw new RunnerException(e);\n    }\n  }\n}\n","sourceCodeStart":370,"sourceCodeEnd":396,"githubUrl":"https://github.com/arduino/Arduino/blob/a0df6e0e83b652c72bc78b0a1376c54d6ebc3bee/arduino-core/src/cc/arduino/packages/uploaders/SerialUploader.java#L370-L396","documentation":"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.","triggerScenarios":"Running uploadUsingPreferences, uploadUsingProgrammer, or burnBootloader when no serial port is selected (empty/missing 'serial.port' preference) while the upload pattern requires {serial.port}.","commonSituations":"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.","solutions":["Select the correct serial port via Tools->Port in the IDE before uploading","Programmatically set the port: PreferencesData.set(\"serial.port\", \"/dev/ttyUSB0\") (or COM port on Windows)","Catch SerialNotFoundException and prompt the user to connect/select a board; refresh the port list after plugging in the device","Verify OS drivers for the board's USB-serial chip (CH340, FTDI, etc.) are installed so the port appears"],"exampleFix":"// before\nuploader.uploadUsingPreferences(buildPath, className, true);\n// after\nif (PreferencesData.get(\"serial.port\") == null || PreferencesData.get(\"serial.port\").isEmpty()) {\n  throw new IllegalArgumentException(\"Select a serial port before uploading\");\n}\nuploader.uploadUsingPreferences(buildPath, className, true);","handlingStrategy":"validation","validationCode":"String port = PreferencesData.get(\"serial.port\");\nif (port == null || port.isEmpty()) throw new IllegalStateException(\"No serial port selected; choose one via Tools->Port\");","typeGuard":null,"tryCatchPattern":"try { uploader.uploadUsingPreferences(buildPath, className, true); } catch (SerialNotFoundException e) { refreshPortListAndPrompt(); }","preventionTips":["Select Tools->Port before uploading","Re-enumerate ports after plugging/unplugging boards","Install USB-serial drivers (CH340/FTDI) so ports appear","In headless flows, assert serial.port is set before invoking upload"],"tags":["serial","port","configuration","upload"],"backgroundTag":"missing-config-value","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"}