What causes "SFTPPUT.Error.Connection" in pentaho/pentaho-kettle?

Check the wrapped cause: JSch 'Auth fail' = credentials; 'Connection refused/timeout' = host/port/firewall; host key errors = known_hosts mismatch.

pentaho/pentaho-kettle · error · KettleException

SFTPPUT.Error.Connection

Error message

SFTPPUT.Error.Connection

What it means

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.

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.

Example fix

// before
data.sftpclient.login( realPassword );
// after — validate inputs before login
if ( realPassword == null || realPassword.isEmpty() ) {
  throw new KettleException( "SFTP password is empty (check variable/field resolution)" );
}
data.sftpclient.setTimeout( 30000 );
data.sftpclient.login( realPassword );

Defensive patterns

Strategy: try-catch

Validate before calling

// before processRow's SFTP connect
if ( realServerName == null || realServerName.isEmpty() ) throw new KettleException("SFTP server not set");
if ( realPassword == null || realPassword.isEmpty() ) throw new KettleException("SFTP password empty — check variable resolution");
new InetSocketAddress(realServerName, realServerPort); // throws if unresolvable

Try / catch

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(...); }

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

AI-assisted analysis of pentaho/pentaho-kettle@f3058517a1 (2026-09-13). Data as JSON: /api/errors/5526f506ce47cc97. Report an issue: GitHub.

Appendix: source

Thrown at plugins/sftpput/impl/src/main/java/org/pentaho/di/trans/steps/sftpput/SFTPPut.java:131

        }

        // Set compression
        data.sftpclient.setCompression( meta.getCompression() );

        // Set proxy?
        String realProxyHost = environmentSubstitute( meta.getProxyHost() );
        if ( !Utils.isEmpty( realProxyHost ) ) {
          // Set proxy
          data.sftpclient.setProxy(
            realProxyHost, environmentSubstitute( meta.getProxyPort() ), environmentSubstitute( meta
              .getProxyUsername() ), environmentSubstitute( meta.getProxyPassword() ), meta.getProxyType() );
        }

        // login to ftp host ...
        data.sftpclient.login( realPassword );

      } catch ( Exception e ) {
        throw new KettleException( BaseMessages.getString( PKG, "SFTPPUT.Error.Connection" ), e );
      }

      // Let's perform some checks

      checkSourceFileField( meta.getSourceFileFieldName(), data );

      checkRemoteFoldernameField( meta.getRemoteDirectoryFieldName(), data );

      checkRemoteFilenameField( meta.getRemoteFilenameFieldName(), data );

      // Move to folder
      if ( meta.getAfterFTPS() == JobEntrySFTPPUT.AFTER_FTPSPUT_MOVE ) {
        checkDestinationFolderField( meta.getDestinationFolderFieldName(), data );
      }
    }

    // Read data top upload
    String sourceData = getInputRowMeta().getString( r, data.indexOfSourceFileFieldName );

View on GitHub (pinned to f3058517a1)