pentaho/pentaho-kettle · error · SshConnectionException

SSH connection failed

Error message

SSH connection failed

What it means

waitForConnection detects that the ConnectFuture completed but isConnected() is false, and rethrows the future's exception wrapped in SshConnectionException('SSH connection failed'). This is the generic transport-level failure of the SSH handshake — the underlying cause is attached.

Solutions

1. Inspect the cause (cf.getException()) printed with this error for the real reason
2. Verify the server supports the SSH-2 protocol and modern key exchange algorithms
3. Test with 'ssh -v user@host' from the Pentaho machine to compare handshake behavior
4. Retry after checking network stability (VPNs, NAT gateways)
5. Check sshd logs for the rejected/dropped connection

Example fix

// before
// swallowing generic failure, hard to diagnose
// after
try { connection.connect(); }
catch (SshConnectionException e) { log.error("SSH connect failed", e.getCause()); }

// pre-check protocol support
// ssh -o BatchMode=yes -o ConnectTimeout=5 user@host exit; echo $?  (0 => handshake works)

try { conn.connect(); }
catch ( SshConnectionException e ) {
  Throwable cause = e.getCause();
  log.error( "SSH transport failure, cause: {}", cause == null ? "unknown" : cause.toString() );
}

When it happens

Trigger: The MINA connect future finishes (not by timeout) but the session never became connected: TCP reset mid-handshake, protocol mismatch, or the server rejected the connection and the future carries an exception.

Common situations: Server running an incompatible/legacy SSH protocol version; connection dropped by a proxy or NAT; server MaxAuthTries or per-source connection limits hit during handshake.

Related errors

• SSH connection failed during await
• Failed to download file:
• Failed to open SFTP session
• SFTPPUT.Error.Connection
• SSH connection failed -

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/core/ssh/mina/MinaSshConnection.java:269

      if ( connectTimeout > 0 ) {
        connected = cf.await( connectTimeout );
      } else {
        connected = cf.await();
      }
    } catch ( IOException e ) {
      throw new SshConnectionException( "SSH connection failed during await", e );
    }

    if ( !connected ) {
      if ( connectTimeout > 0 ) {
        throw new SshTimeoutException( "SSH connection timed out after " + connectTimeout + "ms" );
      }
      throw new SshTimeoutException( "SSH connection failed while waiting with no configured timeout" );
    }

    if ( !cf.isConnected() ) {
      Throwable cause = cf.getException();
      throw new SshConnectionException( "SSH connection failed", cause );
    }
  }

  private ClientSession establishSession( ConnectFuture cf ) throws SshConnectionException {
    ClientSession s = cf.getSession();

    if ( s == null ) {
      throw new SshConnectionException( "SSH connection failed - session is null" );
    }

    return s;
  }

  private void authenticateSession() throws SshConnectionException {
    log( DEBUG, "Starting SSH authentication - Auth type: " + config.getAuthType() );
    boolean authed = tryPublicKeyAuthentication();

    if ( !authed ) {

View on GitHub (pinned to f3058517a1)