pentaho/pentaho-kettle · error · KettleException

JobFTPS.Error.Connecting

JobFTPS.Error.Connecting

Error message

JobFTPS.Error.Connecting

What it means

FTPSConnection.connect() opens the secure connection to the remote host: it configures the data connection and adds a status listener before calling connection.connect(). Any exception during connect sets connection=null and is rethrown as KettleException with localized message JobFTPS.Error.Connecting, parameterized by hostName.

Solutions

  1. Verify host, port, and FTPS mode (explicit/implicit) in the job entry config
  2. Test reachability: ping/telnet host:port from the Pentaho server
  3. Inspect the wrapped cause `e` for TLS or auth specifics
  4. Check firewall rules allowing FTPS control and passive data ports
  5. Confirm credentials and certificate truststore are correct

Example fix

// before
connection.connect(); // host typo, refuses
// after
if ( !hostReachable( hostName, port ) ) {
  throw new KettleException( "Host unreachable before connect: " + hostName );
}
connection.connect();
Defensive patterns

Strategy: retry

Validate before calling

// preflight reachability
try ( Socket s = new Socket() ) {
  s.connect( new InetSocketAddress( hostName, port ), 5000 ); // throws if unreachable
}

Try / catch

try { ftpsConnection.connect(); }
catch ( KettleException ke ) {
  Throwable cause = ke.getCause();
  if ( cause instanceof SSLException ) {
    log.error( "TLS handshake failed; check certificates/mode" );
  } else {
    log.error( "Connect failed to " + hostName + "; check host/port/firewall", cause );
  }
}

Prevention

When it happens

Trigger: buildFTPSConnection -> connect() where the underlying FTPS client throws — unreachable host, refused port, TLS handshake failure, bad credentials, or timeout.

Common situations: Wrong host/port; firewall blocking FTPS (esp. implicit vs explicit mode mismatch); invalid or expired certificates; wrong username/password; network outages.

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/fbb59f21382f1b35. Report an issue: GitHub.

Appendix: source

Thrown at plugins/ftps/impl/src/main/java/org/pentaho/di/job/entries/ftpsget/FTPSConnection.java:174

   * this method is used to connect to a remote host
   *
   * @throws KettleException
   */
  public void connect() throws KettleException {
    try {
      connection =
        FTPConnectionFactory.getInstance( getProperties(
          hostName, portNumber, userName, passWord, connectionType, timeOut, passiveMode ) );
      if ( connection.getConnectionType() == FTPConnection.IMPLICIT_SSL_WITH_CRYPTED_DATA_FTP_CONNECTION
          || connection.getConnectionType() == FTPConnection.IMPLICIT_TLS_WITH_CRYPTED_DATA_FTP_CONNECTION ) {
        // need to upgrade to our custom connection to force crypted data channel
        connection = getSecureDataFTPConnection( connection, passWord, timeOut );
      }
      connection.addFTPStatusListener( this );
      connection.connect();
    } catch ( Exception e ) {
      connection = null;
      throw new KettleException( BaseMessages.getString( PKG, "JobFTPS.Error.Connecting", hostName ), e );
    }
  }

  @VisibleForTesting
  protected FTPConnection getSecureDataFTPConnection( FTPConnection connection, String password, int timeout )
    throws ConfigurationException {
    return new SecureDataFTPConnection( connection, password, timeout );
  }

  private Properties getProperties( String hostname, int port, String username, String password,
    int connectionType, int timeout, boolean passiveMode ) {
    Properties pt = new Properties();
    pt.setProperty( "connection.host", hostname );
    pt.setProperty( "connection.port", String.valueOf( port ) );
    pt.setProperty( "user.login", username );
    pt.setProperty( "user.password", password );
    pt.setProperty( "connection.type", getConnectionType( connectionType ) );
    pt.setProperty( "connection.timeout", String.valueOf( timeout ) );

View on GitHub (pinned to f3058517a1)