arduino/Arduino · error · RunnerException

Board is not selected

Error message

Board is not selected

What it means

Compiler.build() requires a target board to be selected before compiling a sketch. It calls BaseNoGui.getTargetBoard() and if no board is set (null), it aborts with a RunnerException because board-specific parameters (platform, package, vid/pid, build path) cannot be resolved. This is a precondition failure of the build pipeline, not a compilation error in the sketch itself.

Source

Thrown at arduino-core/src/cc/arduino/Compiler.java:168

  public Compiler(File pathToSketch, Sketch sketch) {
    this.pathToSketch = pathToSketch;
    this.sketch = sketch;
    this.verbose = PreferencesData.getBoolean("build.verbose");
  }

  public String build(CompilerProgressListener progListener, boolean exportHex) throws RunnerException, PreferencesMapException, IOException {
    List<CompilerProgressListener> listeners = new ArrayList<>();
    listeners.add(progListener);
    return this.build(listeners, exportHex);
  }

  public String build(List<CompilerProgressListener> progListeners, boolean exportHex) throws RunnerException, PreferencesMapException, IOException {
    this.buildPath = sketch.getBuildPath().getAbsolutePath();
    this.buildCache = BaseNoGui.getCachePath();

    TargetBoard board = BaseNoGui.getTargetBoard();
    if (board == null) {
      throw new RunnerException("Board is not selected");
    }

    TargetPlatform platform = board.getContainerPlatform();
    TargetPackage aPackage = platform.getContainerPackage();
    String vidpid = VIDPID();

    PreferencesMap prefs = loadPreferences(board, platform, aPackage, vidpid);

    MessageConsumerOutputStream out = new MessageConsumerOutputStream(new ProgressAwareMessageConsumer(new I18NAwareMessageConsumer(System.out, System.err), progListeners), "\n");
    MessageConsumerOutputStream err = new MessageConsumerOutputStream(new I18NAwareMessageConsumer(System.err, Compiler.this), "\n");

    callArduinoBuilder(board, platform, aPackage, vidpid, BuilderAction.COMPILE, out, err);

    out.flush();
    err.flush();

    if (exportHex) {
      runActions("hooks.savehex.presavehex", prefs);

View on GitHub (pinned to a0df6e0e83)

Solutions

1. Select a board before building: BaseNoGui.setTargetBoard()/select the board in Tools > Board, ensuring the matching platform/package is installed.
2. Verify the 'board' (and 'target_package'/'target_platform') preferences point to an installed board package.
3. Reinstall the board core package if the selected board id no longer exists in any installed index.
4. Wrap build() in error handling and surface a 'select a board' message to the end user instead of a stack trace.

Example fix

// before
new Compiler(sketch).build(progListeners, exportHex);
// after
if (BaseNoGui.getTargetBoard() == null) {
  BaseNoGui.setTargetBoard("arduino:avr:uno"); // or prompt the user
}
new Compiler(sketch).build(progListeners, exportHex);

if (BaseNoGui.getTargetBoard() == null) { throw new IllegalStateException("Select a board before building"); }

try { compiler.build(listeners, exportHex); } catch (RunnerException e) { if ("Board is not selected".equals(e.getMessage())) { promptBoardSelection(); } else { throw e; } }

When it happens

Trigger: Calling Compiler.build() (directly or via BaseNoGui/IDE build flow) while no board has been selected, i.e. BaseNoGui.getTargetBoard() returns null because Preferences 'board' key is unset or references a non-existent board id.

Common situations: Headless/CLI builds (arduino-builder style usage) where the user forgot to set the board; preferences.txt corrupted or reset so the stored board id no longer maps to an installed package; a board package was uninstalled while it was still the selected board.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• Unable to understand proxy settings
• Could not find tool {0} from package {1}
• Could not find tool {0}
• Can't download {0}: invalid filename or exinsting directory
• CRC doesn't match, file is corrupted. It may be a temporary

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