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.

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)

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 {0}
• Unable to find a way to connect
• Burning bootloader is not supported via network!
• Network upload using programmer not supported

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