arduino/Arduino · error · IOException

SCP error:

Error message

SCP error: 

What it means

Thrown by SCP.ensureAcknowledged when the remote scp process replies with a byte code it does not recognize as success (0), warning (1), or error (2), while also failing to produce a newline-terminated error message. The message includes the unexpected byte value and appears in the SSH file-upload path of Arduino IDE.

Source

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

  private void ensureAcknowledged() throws IOException {
    out.flush();

    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) {

View on GitHub (pinned to a0df6e0e83)

Solutions

1. Remove echo/banner output from the board user's shell startup files (.profile, .bashrc)
2. Update the board's system software (OpenSSH/scp) to a standard version
3. Retry the upload to rule out a transient corrupted stream
4. Use the board's web-based upload mechanism if SSH/SCP stays unreliable

Example fix

// before (.bashrc on board)
echo "Welcome!"
// after
// remove or guard echo statements in non-interactive shells:
[[ $- == *i* ]] && echo "Welcome!"

// pre-check: ensure a clean SSH channel
Process p = new ProcessBuilder("ssh", "root@"+host, "which scp").start();
if (p.waitFor() != 0) throw new IllegalStateException("scp missing on board");

try (SCP scp = new SCP(ssh)) {
    scp.sendFile(local);
} catch (IOException e) {
    if (e.getMessage().startsWith("Uknown SCP error")) {
        // protocol corruption: clean board shell rc files, retry
    }
}

When it happens

Trigger: During open/sendFile/startFolder/endFolder, the remote scp binary sends an unexpected status byte (not 0, 1, or 2) — typically caused by a shell login banner, rc-file output, or a non-standard/patched scp on the Yún-style board.

Common situations: Board firmware or OpenSSH versions where scp emits extra output; user shell dotfiles (.profile, .bashrc) printing text on login, which corrupts the SCP protocol stream.

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

• Uknown 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/06ddc51872d3c88d. Report an issue: GitHub.