What causes "SFTP READDIR failed for path=" in apache/seatunnel?

Inspect the chained SftpException cause for the exact SSH error id.

apache/seatunnel · error · IOException

SFTP READDIR failed for path=

Error message

SFTP READDIR failed for path=

What it means

Thrown by the SFTP list operator when the READDIR (ls) call fails with an error other than 'no such file' — permission denial, connection loss, or other protocol errors. The original SftpException is attached as the cause.

Source

Thrown at seatunnel-connectors-v2/connector-file/connector-file-sftp/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/sftp/system/SFTPFileSystem.java:667

                            String name = entry.getFilename();
                            if (!".".equals(name) && !"..".equals(name)) {
                                try {
                                    consumer.accept(
                                            SFTPFileSystem.this.getFileStatus(
                                                    client, entry, absolute));
                                } catch (IOException e) {
                                    throw new ListingRuntimeException(e);
                                }
                            }
                            return LsEntrySelector.CONTINUE;
                        });
            } catch (ListingRuntimeException e) {
                throw e.ioException;
            } catch (SftpException e) {
                if (e.id == ChannelSftp.SSH_FX_NO_SUCH_FILE) {
                    throw new FileNotFoundException(String.format(E_FILE_NOTFOUND, directory));
                }
                throw new IOException("SFTP READDIR failed for path=" + directory, e);
            }
        }

        @Override
        public void close() throws IOException {
            disconnect(client);
        }
    }

    private static final class ListingRuntimeException extends RuntimeException {
        private final IOException ioException;

        private ListingRuntimeException(IOException ioException) {
            super(ioException);
            this.ioException = ioException;
        }
    }

View on GitHub (pinned to cf67b549a7)

Solutions

Inspect the chained SftpException cause for the exact SSH error id.
Re-establish the SFTP connection (connection pool reconnect) and retry the listing.
Grant the SFTP user read permission on the directory.
Increase/verify keep-alive and timeout settings to avoid mid-operation disconnects.

Example fix

// before
List<FileStatus> fs = list(dir); // throws on stale channel
// after
try { List<FileStatus> fs = list(dir); }
catch (IOException e) { if (isConnectionError(e)) { reconnect(); list(dir); } else throw e; }

Defensive patterns

Strategy: retry

Validate before calling

if (channel == null || !channel.isConnected()) { channel = pool.connect(); }

Try / catch

try { files = listFiles(dir); }
catch (IOException e) {
    if (!(e instanceof FileNotFoundException)) { reconnect(); files = listFiles(dir); }
    else throw e;
}

Prevention

Use bounded retries with backoff for directory scans
Keep SFTP sessions alive during long scans
Grant the SFTP account read permission on scanned directories

When it happens

Trigger: Calling list()/listFiles on an SFTP directory while the channel is broken or the server denies the READDIR (SSH_FX_PERMISSION_DENIED, SSH_FX_FAILURE), i.e. any SftpException whose id != SSH_FX_NO_SUCH_FILE.

Common situations: Idle SFTP connection dropped by server/firewall before the listing; directory unreadable by the SFTP account; server-side failures during large directory scans.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/9006e668802cfc45. Report an issue: GitHub.