{"record":{"id":"5526f506ce47cc97","repo":"pentaho/pentaho-kettle","slug":"sftpput-error-connection","errorCode":null,"errorMessage":"SFTPPUT.Error.Connection","messagePattern":"SFTPPUT\\.Error\\.Connection","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"plugins/sftpput/impl/src/main/java/org/pentaho/di/trans/steps/sftpput/SFTPPut.java","lineNumber":131,"sourceCode":"        }\n\n        // Set compression\n        data.sftpclient.setCompression( meta.getCompression() );\n\n        // Set proxy?\n        String realProxyHost = environmentSubstitute( meta.getProxyHost() );\n        if ( !Utils.isEmpty( realProxyHost ) ) {\n          // Set proxy\n          data.sftpclient.setProxy(\n            realProxyHost, environmentSubstitute( meta.getProxyPort() ), environmentSubstitute( meta\n              .getProxyUsername() ), environmentSubstitute( meta.getProxyPassword() ), meta.getProxyType() );\n        }\n\n        // login to ftp host ...\n        data.sftpclient.login( realPassword );\n\n      } catch ( Exception e ) {\n        throw new KettleException( BaseMessages.getString( PKG, \"SFTPPUT.Error.Connection\" ), e );\n      }\n\n      // Let's perform some checks\n\n      checkSourceFileField( meta.getSourceFileFieldName(), data );\n\n      checkRemoteFoldernameField( meta.getRemoteDirectoryFieldName(), data );\n\n      checkRemoteFilenameField( meta.getRemoteFilenameFieldName(), data );\n\n      // Move to folder\n      if ( meta.getAfterFTPS() == JobEntrySFTPPUT.AFTER_FTPSPUT_MOVE ) {\n        checkDestinationFolderField( meta.getDestinationFolderFieldName(), data );\n      }\n    }\n\n    // Read data top upload\n    String sourceData = getInputRowMeta().getString( r, data.indexOfSourceFileFieldName );","sourceCodeStart":113,"sourceCodeEnd":149,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/plugins/sftpput/impl/src/main/java/org/pentaho/di/trans/steps/sftpput/SFTPPut.java#L113-L149","documentation":"KettleException thrown in SFTPPut.processRow() when establishing the SFTP session fails — any exception while creating the SFTP client, connecting, or logging in with realPassword is wrapped with the SFTPPUT.Error.Connection message.","triggerScenarios":"JSch getSession/connect or sftpclient.login(realPassword) throws: unreachable host/port, wrong username or password, rejected host key, server closed connection, or auth method (password vs keyboard-interactive/pubkey) not permitted.","commonSituations":"Password (or password field value) mistyped or the variable in the password field doesn't resolve; SFTP server moved or port changed; host key changed after server reinstall (host key rejection); account locked or shell restricted to sftp-only causing auth quirks; firewall dropping the connection.","solutions":["Check the wrapped cause: JSch 'Auth fail' = credentials; 'Connection refused/timeout' = host/port/firewall; host key errors = known_hosts mismatch.","Verify server name/port and that password authentication is enabled on the SFTP server.","Test with an independent SFTP client (sftp/WinSCP) using the exact same user/password.","Remove the stale host key from ~/.ssh/known_hosts if the server's key legitimately changed.","If using variables for credentials, confirm they resolve at runtime (enable Kettle debug logging) and that the connection timeout is adequate."],"exampleFix":"// before\ndata.sftpclient.login( realPassword );\n// after — validate inputs before login\nif ( realPassword == null || realPassword.isEmpty() ) {\n  throw new KettleException( \"SFTP password is empty (check variable/field resolution)\" );\n}\ndata.sftpclient.setTimeout( 30000 );\ndata.sftpclient.login( realPassword );","handlingStrategy":"try-catch","validationCode":"// before processRow's SFTP connect\nif ( realServerName == null || realServerName.isEmpty() ) throw new KettleException(\"SFTP server not set\");\nif ( realPassword == null || realPassword.isEmpty() ) throw new KettleException(\"SFTP password empty — check variable resolution\");\nnew InetSocketAddress(realServerName, realServerPort); // throws if unresolvable","typeGuard":null,"tryCatchPattern":"try { data.sftpclient.login(realPassword); } catch ( Exception e ) { Throwable c = e.getCause(); if ( c != null && c.getMessage() != null && c.getMessage().contains(\"Auth fail\") ) { // credentials issue: alert, don't retry blindly } else { // transient: retry with backoff } throw new KettleException(...); }","preventionTips":["Test credentials with a standalone SFTP client before configuring the step.","Use named connections / secure variable resolution for passwords.","Monitor for host key changes on SFTP servers and update known_hosts deliberately.","Set sensible connect/timeout values and verify firewall rules for the SFTP port."],"tags":["kettle","sftp","ssh","authentication","network"],"backgroundTag":"connection-refused","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}