pentaho/pentaho-kettle · error · SftpException

Failed to list directory:

Error message

Failed to list directory: 

What it means

MinaSftpSession.list() enumerates a remote SFTP directory via Apache MINA SSHD and wraps IOException in SftpException with 'Failed to list directory: <path>'. It indicates the remote directory listing could not be completed at the transport level.

Solutions

1. Verify the remote path exists and is a directory (call exists() first)
2. Check SFTP user permissions on the remote directory
3. Test connection stability/timeouts; reconnect the session before retrying
4. Inspect the wrapped IOException cause for the transport-level detail

Example fix

// before
List<SftpFile> files = session.list("/data/reports"); // path missing
// after
if (session.exists("/data/reports")) {
  List<SftpFile> files = session.list("/data/reports");
} else {
  session.getMkdirs("/data/reports");
}

// Pre-check remote directory before listing
if (!session.exists(remotePath)) throw new IllegalStateException("Remote path does not exist: " + remotePath);
if (!session.isDirectory(remotePath)) throw new IllegalStateException("Remote path is not a directory: " + remotePath);

try {
  List<SftpFile> files = session.list(remotePath);
} catch (SftpException e) {
  if (e.getMessage().startsWith("Failed to list directory")) {
    log.error("SFTP listing failed for " + remotePath, e.getCause());
    reconnectAndRetry(remotePath);
  } else throw e;
}

When it happens

Trigger: Calling list(path) when the remote path does not exist, the connection is broken/timed out mid-read, or the server denies directory read while opening fails with IOException.

Common situations: Wrong remote path/typo; SSH session dropped due to network issue or server timeout; permission denied on the remote directory; server closed connection.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Failed to download file:
• Failed to open SFTP session
• JobFTPS.Error.RetrievingFilenames
• Max connection attempts reached
• SFTPPUT.Error.Connection

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/core/ssh/mina/MinaSftpSession.java:51

    this.client = client;
  }

  @Override
  public List<SftpFile> list( String path ) throws SftpException {
    try {
      List<SftpFile> out = new ArrayList<>();
      for ( SftpClient.DirEntry e : client.readDir( path ) ) {
        Attributes a = e.getAttributes();
        Instant mtime = Instant.EPOCH;
        if ( a.getModifyTime() != null ) {
          // getModifyTime returns a FileTime; convert via toMillis()
          mtime = Instant.ofEpochMilli( a.getModifyTime().toMillis() );
        }
        out.add( new SftpFile( e.getFilename(), a.isDirectory(), a.getSize(), mtime ) );
      }
      return out;
    } catch ( IOException e ) {
      throw new SftpException( "Failed to list directory: " + path, e );
    }
  }

  @Override
  public boolean exists( String path ) throws SftpException {
    try {
      client.stat( path );
      return true;
    } catch ( IOException e ) {
      return false;
    }
  }

  @Override
  public boolean isDirectory( String path ) throws SftpException {
    try {
      return client.stat( path ).isDirectory();
    } catch ( IOException e ) {

View on GitHub (pinned to f3058517a1)