arduino/Arduino · error · IOException

Uknown SCP error:

Error message

Uknown SCP error: 

What it means

The SCP implementation in Arduino IDE reads a status byte from the remote scp process; valid values are 0 (ok), 1 (warning), and 2 (fatal error). Any other byte means the SCP protocol stream is corrupted, and this IOException is thrown with the offending byte value.

Solutions

1. Clean the board user's shell startup files so they emit nothing on non-interactive logins
2. Verify scp exists and works on the board (ssh board 'which scp')
3. Update the board OS/firmware to a supported version
4. Retry the upload; check SSH connectivity with a plain ssh session

Example fix

// before (.profile on board)
figlet hello
// after
// guard non-interactive sessions:
[ -z "$PS1" ] && return

// confirm remote scp responds with clean protocol
ssh.exec("command -v scp"); // must succeed with no extra output

try {
    scp.sendFile(file);
} catch (IOException e) {
    if (e.getMessage().contains("Uknown SCP error")) {
        // inspect byte in message; sanitize startup scripts and retry
    }
}

When it happens

Trigger: ensureAcknowledged, invoked from open/sendFile/startFolder/endFolder, reads a status byte outside {0,1,2} — almost always because the remote side printed something (login banners, rc files, or scp not present) before/instead of protocol data.

Common situations: Yún/Linux-based boards with noisy shell startup scripts, outdated board OpenSSH builds, or a remote scp binary missing/replaced so the SSH channel delivers shell output instead of SCP acknowledgment bytes.

Understand the failure class

Background: "invalid response format", "malformed payload", "missing data field": when an API returns 200 but the response shape is wrong — this error's family across 23 libraries.

Related errors

• SCP error:
• Unable to connect to
• Burning bootloader is not supported via network!
• Can't burn bootloader via SSH
• Couldn't find a Board on the selected port. Check that you…

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

Appendix: source

Thrown at arduino-core/src/cc/arduino/packages/ssh/SCP.java:93

    int b = in.read();

    if (b == 0) return;
    if (b == -1) return;

    if (b == 1 || b == 2) {
      StringBuilder sb = new StringBuilder();
      sb.append("SCP error: ");

      int c;
      do {
        c = in.read();
        sb.append((char) c);
      } while (c != '\n');

      throw new IOException(sb.toString());
    }

    throw new IOException("Uknown SCP error: " + b);
  }

  public void sendFile(File localFile) throws IOException {
    sendFile(localFile, localFile.getName());
  }

  public void sendFile(File localFile, String remoteFile) throws IOException {
    out.write(("C0644 " + localFile.length() + " " + remoteFile + "\n").getBytes());
    ensureAcknowledged();

    FileInputStream fis = null;
    try {
      fis = new FileInputStream(localFile);
      byte[] buf = new byte[4096];
      while (true) {
        int len = fis.read(buf, 0, buf.length);
        if (len <= 0) break;
        out.write(buf, 0, len);

View on GitHub (pinned to a0df6e0e83)