pentaho/pentaho-kettle · error · KettleException

SSH.Error.ErrorConnecting

SSH.Error.ErrorConnecting

Error message

SSH.Error.ErrorConnecting

What it means

SSH.Error.ErrorConnecting is thrown by openSshConnection when establishing the SSH session to the server fails for any reason (unreachable host, wrong port, authentication rejection, proxy failure). The partially-created connection is closed and the original exception is wrapped in a KettleException naming the server and username. It covers the entire connect() call including auth setup.

Solutions

1. Verify hostname and port are correct and reachable (test with `ssh user@host -p port` or `nc -zv host port`)
2. Confirm username/password or key credentials are valid on the target server
3. Check proxy settings (host/port/user/password) in the step if a proxy is configured
4. Inspect the wrapped cause exception for the underlying reason (timeout vs auth failure)

Example fix

// before
server = "prod-db.example.com"; port = 2222; // wrong port, server listens on 22
// after
server = "prod-db.example.com"; port = 22;

// pre-flight check in a shell before running the ETL:
nc -zv $SERVER $PORT && ssh -o BatchMode=yes -o ConnectTimeout=5 $USER@$SERVER true

try {
  sshStepRun();
} catch (KettleException e) {
  logError("SSH connect to " + server + " failed: " + e.getCause());
  if (e.getCause() instanceof java.net.ConnectException) { retryWithBackoff(); }
  else { failStep(); }
}

When it happens

Trigger: Calling connect() on the SSH client with wrong hostname/port (connection refused/timeout), or invalid credentials (password or private key rejected), or a misconfigured proxy.

Common situations: Typo in hostname, server firewall blocking port 22, disabled password auth on server while step uses password, key authorized but passphrase wrong, DNS resolution failure.

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

• SSH connection failed -
• Failed to open SFTP session
• SFTPPUT.Error.Connection
• SSH connection failed during await
• CmsTokenProvider: Keycloak token request failed — HTTP

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/ssh/SSHData.java:161

      configureAuthentication( config, params.getBowl(), params.isUseKey(),
          params.getKeyFilename(), params.getPassPhrase(), params.getPassword(), params.getSpace() );

      // Configure proxy if specified
      configureProxy( config, params.getProxyhost(), params.getProxyport(),
          params.getProxyusername(), params.getProxypassword() );

      // Create and connect
      connection = SshConnectionFactory.defaultFactory().open( config );
      connection.connect();

      return connection;

    } catch ( Exception e ) {
      // Something wrong happened - clean up and re-throw
      if ( connection != null ) {
        connection.close();
      }
      throw new KettleException( BaseMessages.getString( PKG, "SSH.Error.ErrorConnecting", params.getServer(), params.getUsername() ), e );
    }
  }

  /**
   * Configures authentication for the SSH connection using secure in-memory approach.
   */
  private static void configureAuthentication( SshConfig config, Bowl bowl, boolean useKey,
      String keyFilename, String passPhrase, String password, VariableSpace space ) throws KettleException {

    if ( useKey ) {
      configureKeyAuthentication( config, bowl, keyFilename, passPhrase, space );
    } else {
      config.authType( SshConfig.AuthType.PASSWORD ).password( password );
    }
  }

  /**
   * Configures key-based authentication using secure in-memory key handling.

View on GitHub (pinned to f3058517a1)