{"record":{"id":"d3b7be11b10b305c","repo":"pentaho/pentaho-kettle","slug":"ssh-error-errorconnecting","errorCode":"SSH.Error.ErrorConnecting","errorMessage":"SSH.Error.ErrorConnecting","messagePattern":"SSH\\.Error\\.ErrorConnecting","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/ssh/SSHData.java","lineNumber":161,"sourceCode":"      configureAuthentication( config, params.getBowl(), params.isUseKey(),\n          params.getKeyFilename(), params.getPassPhrase(), params.getPassword(), params.getSpace() );\n\n      // Configure proxy if specified\n      configureProxy( config, params.getProxyhost(), params.getProxyport(),\n          params.getProxyusername(), params.getProxypassword() );\n\n      // Create and connect\n      connection = SshConnectionFactory.defaultFactory().open( config );\n      connection.connect();\n\n      return connection;\n\n    } catch ( Exception e ) {\n      // Something wrong happened - clean up and re-throw\n      if ( connection != null ) {\n        connection.close();\n      }\n      throw new KettleException( BaseMessages.getString( PKG, \"SSH.Error.ErrorConnecting\", params.getServer(), params.getUsername() ), e );\n    }\n  }\n\n  /**\n   * Configures authentication for the SSH connection using secure in-memory approach.\n   */\n  private static void configureAuthentication( SshConfig config, Bowl bowl, boolean useKey,\n      String keyFilename, String passPhrase, String password, VariableSpace space ) throws KettleException {\n\n    if ( useKey ) {\n      configureKeyAuthentication( config, bowl, keyFilename, passPhrase, space );\n    } else {\n      config.authType( SshConfig.AuthType.PASSWORD ).password( password );\n    }\n  }\n\n  /**\n   * Configures key-based authentication using secure in-memory key handling.","sourceCodeStart":143,"sourceCodeEnd":179,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/ssh/SSHData.java#L143-L179","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify hostname and port are correct and reachable (test with `ssh user@host -p port` or `nc -zv host port`)","Confirm username/password or key credentials are valid on the target server","Check proxy settings (host/port/user/password) in the step if a proxy is configured","Inspect the wrapped cause exception for the underlying reason (timeout vs auth failure)"],"exampleFix":"// before\nserver = \"prod-db.example.com\"; port = 2222; // wrong port, server listens on 22\n// after\nserver = \"prod-db.example.com\"; port = 22;","handlingStrategy":"try-catch","validationCode":"// pre-flight check in a shell before running the ETL:\nnc -zv $SERVER $PORT && ssh -o BatchMode=yes -o ConnectTimeout=5 $USER@$SERVER true","typeGuard":null,"tryCatchPattern":"try {\n  sshStepRun();\n} catch (KettleException e) {\n  logError(\"SSH connect to \" + server + \" failed: \" + e.getCause());\n  if (e.getCause() instanceof java.net.ConnectException) { retryWithBackoff(); }\n  else { failStep(); }\n}","preventionTips":["Test host/port/credentials manually before scheduling","Use environment variables for host/port so environments are explicit","Keep proxy config in sync with actual network topology","Check the wrapped cause to distinguish auth vs network failures"],"tags":["ssh","network","connection","authentication"],"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"}