{"record":{"id":"7e16f73bcf814aa6","repo":"pentaho/pentaho-kettle","slug":"ssh-connection-failed-minasshconnection","errorCode":null,"errorMessage":"SSH connection failed","messagePattern":"SSH connection failed","errorType":"exception","errorClass":"SshConnectionException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/core/ssh/mina/MinaSshConnection.java","lineNumber":269,"sourceCode":"      if ( connectTimeout > 0 ) {\n        connected = cf.await( connectTimeout );\n      } else {\n        connected = cf.await();\n      }\n    } catch ( IOException e ) {\n      throw new SshConnectionException( \"SSH connection failed during await\", e );\n    }\n\n    if ( !connected ) {\n      if ( connectTimeout > 0 ) {\n        throw new SshTimeoutException( \"SSH connection timed out after \" + connectTimeout + \"ms\" );\n      }\n      throw new SshTimeoutException( \"SSH connection failed while waiting with no configured timeout\" );\n    }\n\n    if ( !cf.isConnected() ) {\n      Throwable cause = cf.getException();\n      throw new SshConnectionException( \"SSH connection failed\", cause );\n    }\n  }\n\n  private ClientSession establishSession( ConnectFuture cf ) throws SshConnectionException {\n    ClientSession s = cf.getSession();\n\n    if ( s == null ) {\n      throw new SshConnectionException( \"SSH connection failed - session is null\" );\n    }\n\n    return s;\n  }\n\n  private void authenticateSession() throws SshConnectionException {\n    log( DEBUG, \"Starting SSH authentication - Auth type: \" + config.getAuthType() );\n    boolean authed = tryPublicKeyAuthentication();\n\n    if ( !authed ) {","sourceCodeStart":251,"sourceCodeEnd":287,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/core/ssh/mina/MinaSshConnection.java#L251-L287","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the cause (cf.getException()) printed with this error for the real reason","Verify the server supports the SSH-2 protocol and modern key exchange algorithms","Test with 'ssh -v user@host' from the Pentaho machine to compare handshake behavior","Retry after checking network stability (VPNs, NAT gateways)","Check sshd logs for the rejected/dropped connection"],"exampleFix":"// before\n// swallowing generic failure, hard to diagnose\n// after\ntry { connection.connect(); }\ncatch (SshConnectionException e) { log.error(\"SSH connect failed\", e.getCause()); }","handlingStrategy":"try-catch","validationCode":"// pre-check protocol support\n// ssh -o BatchMode=yes -o ConnectTimeout=5 user@host exit; echo $?  (0 => handshake works)","typeGuard":null,"tryCatchPattern":"try { conn.connect(); }\ncatch ( SshConnectionException e ) {\n  Throwable cause = e.getCause();\n  log.error( \"SSH transport failure, cause: {}\", cause == null ? \"unknown\" : cause.toString() );\n}","preventionTips":["Keep the SSHD client library and server on modern, compatible versions","Inspect the attached cause before assuming config problems","Test handshake with 'ssh -v' when debugging","Avoid intermediate proxies that mangle long-lived connections"],"tags":["ssh","network","handshake"],"backgroundTag":"network-request-failed","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"}