{"record":{"id":"837c8dafe67c120e","repo":"arduino/Arduino","slug":"uknown-scp-error","errorCode":null,"errorMessage":"Uknown SCP error: ","messagePattern":"Uknown SCP error: ","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"arduino-core/src/cc/arduino/packages/ssh/SCP.java","lineNumber":93,"sourceCode":"    int b = in.read();\n\n    if (b == 0) return;\n    if (b == -1) return;\n\n    if (b == 1 || b == 2) {\n      StringBuilder sb = new StringBuilder();\n      sb.append(\"SCP error: \");\n\n      int c;\n      do {\n        c = in.read();\n        sb.append((char) c);\n      } while (c != '\\n');\n\n      throw new IOException(sb.toString());\n    }\n\n    throw new IOException(\"Uknown SCP error: \" + b);\n  }\n\n  public void sendFile(File localFile) throws IOException {\n    sendFile(localFile, localFile.getName());\n  }\n\n  public void sendFile(File localFile, String remoteFile) throws IOException {\n    out.write((\"C0644 \" + localFile.length() + \" \" + remoteFile + \"\\n\").getBytes());\n    ensureAcknowledged();\n\n    FileInputStream fis = null;\n    try {\n      fis = new FileInputStream(localFile);\n      byte[] buf = new byte[4096];\n      while (true) {\n        int len = fis.read(buf, 0, buf.length);\n        if (len <= 0) break;\n        out.write(buf, 0, len);","sourceCodeStart":75,"sourceCodeEnd":111,"githubUrl":"https://github.com/arduino/Arduino/blob/a0df6e0e83b652c72bc78b0a1376c54d6ebc3bee/arduino-core/src/cc/arduino/packages/ssh/SCP.java#L75-L111","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Clean the board user's shell startup files so they emit nothing on non-interactive logins","Verify scp exists and works on the board (ssh board 'which scp')","Update the board OS/firmware to a supported version","Retry the upload; check SSH connectivity with a plain ssh session"],"exampleFix":"// before (.profile on board)\nfiglet hello\n// after\n// guard non-interactive sessions:\n[ -z \"$PS1\" ] && return","handlingStrategy":"try-catch","validationCode":"// confirm remote scp responds with clean protocol\nssh.exec(\"command -v scp\"); // must succeed with no extra output","typeGuard":null,"tryCatchPattern":"try {\n    scp.sendFile(file);\n} catch (IOException e) {\n    if (e.getMessage().contains(\"Uknown SCP error\")) {\n        // inspect byte in message; sanitize startup scripts and retry\n    }\n}","preventionTips":["Remove banners/echo from root's dotfiles on the board","Verify scp exists on the board firmware","Retry on transient corruption before failing the upload"],"tags":["ssh","scp","upload","protocol"],"backgroundTag":"unexpected-api-response-shape","analyzedSha":"a0df6e0e83b652c72bc78b0a1376c54d6ebc3bee","analyzedAt":"2026-09-06T10:13:38.901Z","contentChangedAt":"2026-09-06T10:13:38.901Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}