arduino/Arduino · error · RunnerException

Unable to connect to {0}

Error message

Unable to connect to {0}

What it means

When the SSH session to a network board fails with a JSchException whose message contains 'Connection refused', the uploader translates it into this RunnerException naming the board address. It means nothing was listening/accepting on the board's SSH port at that address.

Source

Thrown at arduino-core/src/cc/arduino/packages/uploaders/SSHUploader.java:148

      if (!coreMissesRemoteUploadTool && mergedSketch.exists()) {
        sketchToCopy = mergedSketch;
      } else {
        sketchToCopy = new CompilerUtils().findCompiledSketch(prefs);
      }
      scpFiles(scp, ssh, sourcePath, sketchToCopy, warningsAccumulator);

      if (coreMissesRemoteUploadTool) {
        ssh.execSyncCommand("merge-sketch-with-bootloader.lua /tmp/sketch.hex", System.out, System.err);
      }

      return runUploadTool(ssh, prefs);
    } catch (JSchException e) {
      String message = e.getMessage();
      if (message.contains("Auth cancel") || message.contains("Auth fail") || message.contains("authentication fail")) {
        return false;
      }
      if (e.getMessage().contains("Connection refused")) {
        throw new RunnerException(I18n.format(tr("Unable to connect to {0}"), port.getAddress()));
      }
      throw new RunnerException(e);
    } catch (Exception e) {
      throw new RunnerException(e);
    } finally {
      if (scp != null) {
        scp.close();
      }
      if (session != null) {
        session.disconnect();
      }
    }
  }

  private boolean runUploadTool(SSH ssh, PreferencesMap prefs) throws Exception {
    ssh.execSyncCommand("kill-bridge");

    if (verbose) {

View on GitHub (pinned to a0df6e0e83)

Solutions

  1. Confirm the board address and that port 22 is reachable (telnet/nc check)
  2. Wait for the board to finish booting and retry
  3. Reset or power-cycle the board
  4. Check the board firmware includes/starts sshd; reinstall if needed

Example fix

// before
port = 192.168.240.99 (wrong/stale)
// after
// discover actual address, then:
ssh root@192.168.240.1  // verify connectivity before uploading
Defensive patterns

Strategy: retry

Validate before calling

// TCP reachability pre-check before SSH upload
try (Socket s = new Socket()) {
    s.connect(new InetSocketAddress(host, 22), 3000); // ok
} catch (IOException e) {
    throw new IllegalStateException("Board SSH not reachable: " + host);
}

Try / catch

try {
    uploadViaSsh(port);
} catch (RunnerException e) {
    if (e.getMessage().startsWith("Unable to connect to")) {
        // wait for board boot, power-cycle, then retry
        Thread.sleep(10000);
    }
}

Prevention

When it happens

Trigger: uploadUsingPreferences calls ssh.connect() to the board's address and the TCP connection is refused — the board's SSH daemon is not running, the address is wrong, or the board is booting/offline.

Common situations: Yún boards that just rebooted (SSH takes time to start), wrong IP/port configured, board firmware where sshd is disabled, or firewall/port forwarding issues.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

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