{"record":{"id":"d0683534454d106f","repo":"arduino/Arduino","slug":"couldn-t-find-a-board-on-the-selected-port-check","errorCode":null,"errorMessage":"Couldn't find a Board on the selected port. Check that you have the correct port selected.  If it is correct, try pressing the board's reset button after initiating the upload.","messagePattern":"Couldn't find a Board on the selected port\\. Check that you have the correct port selected\\.  If it is correct, try pressing the board's reset button after initiating the upload\\.","errorType":"exception","errorClass":"RunnerException","httpStatus":null,"severity":"error","filePath":"arduino-core/src/cc/arduino/packages/uploaders/SerialUploader.java","lineNumber":277,"sourceCode":"      }\n\n      // Keep track of port that disappears\n      before = now;\n      Thread.sleep(250);\n      elapsed += 250;\n\n      // On Windows and OS X, it can take a few seconds for the port to disappear and\n      // come back, so use a time out before assuming that the selected port is the\n      // bootloader (not the sketch).\n      if (elapsed >= 5000 && now.contains(uploadPort)) {\n        if (verbose)\n          System.out.println(\"Uploading using selected port: \" + uploadPort);\n        return uploadPort;\n      }\n    }\n\n    // Something happened while detecting port\n    throw new RunnerException(tr(\"Couldn't find a Board on the selected port. Check that you have the correct port selected.  If it is correct, try pressing the board's reset button after initiating the upload.\"), false);\n  }\n\n  private boolean uploadUsingProgrammer(String buildPath, String className) throws Exception {\n\n    TargetPlatform targetPlatform = BaseNoGui.getTargetPlatform();\n    String programmer = PreferencesData.get(\"programmer\");\n    if (programmer.contains(\":\")) {\n      String[] split = programmer.split(\":\", 2);\n      targetPlatform = BaseNoGui.getCurrentTargetPlatformFromPackage(split[0]);\n      programmer = split[1];\n    }\n\n    PreferencesMap prefs = PreferencesData.getMap();\n    PreferencesMap boardPreferences = BaseNoGui.getBoardPreferences();\n    if (boardPreferences != null) {\n      prefs.putAll(boardPreferences);\n    }\n    PreferencesMap programmerPrefs = targetPlatform.getProgrammer(programmer);","sourceCodeStart":259,"sourceCodeEnd":295,"githubUrl":"https://github.com/arduino/Arduino/blob/a0df6e0e83b652c72bc78b0a1376c54d6ebc3bee/arduino-core/src/cc/arduino/packages/uploaders/SerialUploader.java#L259-L295","documentation":"SerialUploader.waitForUploadPort waits for the board to disappear and re-enumerate on a (possibly new) serial port after triggering the 1200-baud bootloader reset. If no matching port appears within the timeout, it throws this RunnerException telling the user the IDE never saw the board re-open its bootloader port.","triggerScenarios":"During uploadUsingPreferences on 32u4/native-USB boards (Leonardo, Micro, etc.): the board did not reset, or the bootloader port had a different identity/never appeared before timeout.","commonSituations":"Leonardo-class boards whose sketch crashes so the 1200bps touch does nothing; driver problems leaving ports unenumerated; user selected the wrong port; board held in a bad state; USB cable/hub issues.","solutions":["Press the board's reset button twice quickly right after upload starts (double-tap into bootloader)","Select the correct port and verify with the Tools > Port menu after replugging","Try a different USB cable/port (avoid hubs) and reinstall drivers","Manually put the board in bootloader mode, or recover via another ISP programmer if the sketch bricks reset"],"exampleFix":"// before: no board visible after upload start\n// Tools>Port: /dev/ttyACM0 (greyed)\n// after: double-tap reset button\n// bootloader port reappears: /dev/ttyACM0 -> upload completes","handlingStrategy":"try-catch","validationCode":"// Verify port enumerates before upload\nSerialPort p = SerialPort.getCommPort(portName);\nif (!p.openPort()) throw new IllegalStateException(\"Board port not present: \" + portName);","typeGuard":null,"tryCatchPattern":"try {\n    serialUploader.uploadUsingPreferences(...);\n} catch (RunnerException e) {\n    if (e.getMessage().contains(\"Couldn't find a Board on the selected port\")) {\n        // prompt: double-tap reset, recheck port, retry\n    }\n}","preventionTips":["Learn the double-tap reset maneuver for 32u4 boards","Use good USB cables, avoid hubs","Reinstall board drivers if ports don't enumerate","Verify the selected port matches the board before uploading"],"tags":["serial","upload","bootloader","port-detection"],"backgroundTag":"resource-not-found","analyzedSha":"a0df6e0e83b652c72bc78b0a1376c54d6ebc3bee","analyzedAt":"2026-09-06T10:13:38.901Z","contentChangedAt":"2026-09-06T10:13:38.901Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}