pentaho/pentaho-kettle · error · FileSystemException

vfs.provider.sftp/connect.error

vfs.provider.sftp/connect.error

Error message

vfs.provider.sftp/connect.error

What it means

Thrown by SftpFileSystemWindowsProvider.createSession() when establishing the JSch SFTP session (with username/password from the authenticator) throws for any reason; it is wrapped in a FileSystemException keyed to 'vfs.provider.sftp/connect.error'.

Solutions

1. Test connectivity: ping/ssh to host:port; confirm the server is listening and reachable
2. Verify username/password in the VFS URI or UserAuthenticator
3. Handle host-key acceptance (set trusted host key or adjust StrictHostKeyChecking in fileSystemOptions)
4. Inspect the wrapped cause 'e' for the underlying JSch error (timeout, auth fail, etc.)
5. Retry on transient network errors with backoff

Example fix

// before
FileSystemManager fsManager = VFS.getManager();
FileObject fo = fsManager.resolveFile( "sftp://badhost/data" );
// after
try {
  FileObject fo = fsManager.resolveFile( "sftp://badhost/data" );
} catch ( FileSystemException e ) {
  if ( e.getMessage().contains( "connect.error" ) ) {
    throw new KettleException( "Cannot connect to SFTP server; check host, credentials and network", e );
  }
  throw e;
}

// Pre-flight: check TCP reachability
try ( Socket s = new Socket( host, 22 ) ) {
  System.out.println( "SFTP port reachable" );
} catch ( IOException e ) {
  System.out.println( "Host/port unreachable: " + e.getMessage() );
}

try {
  FileObject fo = fsManager.resolveFile( "sftp://user@host/path" );
} catch ( FileSystemException e ) {
  // e.getMessage() == "vfs.provider.sftp/connect.error"; inspect e.getCause() (JSch) for auth vs network
  if ( e.getCause() instanceof JSchException ) {
    JSchException je = (JSchException) e.getCause();
    // handle auth failure vs timeout vs host key
  }
}

When it happens

Trigger: doCreateFileSystem() connecting to an SFTP server: unreachable host/port, wrong credentials, unknown host key, SSH handshake failure, JSch library errors.

Common situations: Wrong hostname or port in vfs.sftp.* URI, expired or changed password, host key not in known_hosts (StrictHostKeyChecking), firewall blocking port 22, server temporarily down.

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

• An unexpected error has occurred
• ConnectionFileSystem.FailedTransformProviderFilename
• Could not get the groups of the current user (error code: )
• Could not get user name on remote host (error code: )
• Failed to open SFTP session

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

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/core/vfs/SftpFileSystemWindowsProvider.java:78

   * Creates a new Session.  Note that this method is borrowed from the parent class and should mirror it if the
   * commons-vfs2 library is updated.
   *
   * @return A Session, never null.
   */
  static Session createSession( final GenericFileName rootName, final FileSystemOptions fileSystemOptions )
    throws FileSystemException {
    UserAuthenticationData authData = null;
    try {
      authData = UserAuthenticatorUtils.authenticate( fileSystemOptions, AUTHENTICATOR_TYPES );

      return SftpClientFactory.createConnection( rootName.getHostName(), rootName.getPort(),
        UserAuthenticatorUtils.getData( authData, UserAuthenticationData.USERNAME,
          UserAuthenticatorUtils.toChar( rootName.getUserName() ) ),
        UserAuthenticatorUtils.getData( authData, UserAuthenticationData.PASSWORD,
          UserAuthenticatorUtils.toChar( rootName.getPassword() ) ),
        fileSystemOptions );
    } catch ( final Exception e ) {
      throw new FileSystemException( "vfs.provider.sftp/connect.error", rootName, e );
    } finally {
      UserAuthenticatorUtils.cleanup( authData );
    }
  }

  @Override
  protected FileSystem doCreateFileSystem( FileName name, FileSystemOptions fileSystemOptions )
    throws FileSystemException {
    return new SftpFileSystemWindows(
      (GenericFileName) name, createSession( (GenericFileName) name, fileSystemOptions ), fileSystemOptions );
  }

}

View on GitHub (pinned to f3058517a1)