apache/seatunnel · error · IOException

SFTP lstat failed for path=

Error message

SFTP lstat failed for path=

What it means

getFileStatus() throws this IOException when the SFTP lstat call fails with any error other than 'no such file' — e.g. permission denial, connection loss, or a protocol-level error. The original SftpException is chained so the real cause is preserved.

Source

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

            this.client = client;
        }

        @Override
        public FileStatus getFileStatus(Path path) throws IOException {
            Path absolute;
            try {
                absolute = makeAbsolute(new Path(client.pwd()), path);
                if (absolute.getParent() == null) {
                    return SFTPFileSystem.this.getFileStatus(client, absolute);
                }
                SftpATTRS attrs = client.lstat(absolute.toUri().getPath());
                return SFTPFileSystem.this.getFileStatus(
                        client, absolute.getName(), attrs, absolute.getParent());
            } catch (SftpException e) {
                if (e.id == ChannelSftp.SSH_FX_NO_SUCH_FILE) {
                    throw new FileNotFoundException(String.format(E_FILE_NOTFOUND, path));
                }
                throw new IOException("SFTP lstat failed for path=" + path, e);
            }
        }

        @Override
        public void list(Path directory, FileStatusConsumer consumer) throws IOException {
            Path absolute;
            try {
                absolute = makeAbsolute(new Path(client.pwd()), directory);
                client.ls(
                        absolute.toUri().getPath(),
                        entry -> {
                            String name = entry.getFilename();
                            if (!".".equals(name) && !"..".equals(name)) {
                                try {
                                    consumer.accept(
                                            SFTPFileSystem.this.getFileStatus(
                                                    client, entry, absolute));
                                } catch (IOException e) {

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Inspect the chained SftpException cause for the exact SSH error id/reason.
  2. Ensure the SFTP connection pool keeps channels alive or reconnects; retry the stat after reconnection.
  3. Verify the SFTP user has read/execute permission on every component of the path.
  4. Check network/firewall stability between the job and the SFTP server (timeouts, idle disconnects).

Example fix

// before
FileStatus st = sftpFs.getFileStatus(path); // may throw on stale channel
// after
try {
    FileStatus st = sftpFs.getFileStatus(path);
} catch (IOException e) {
    if (e.getCause() instanceof SftpException) { reconnectAndRetry(path); }
    else throw e;
}
Defensive patterns

Strategy: retry

Validate before calling

// lstat failures other than missing file are usually transient/connection related
if (channel == null || !channel.isConnected()) { channel = pool.connect(); }

Try / catch

try { FileStatus st = sftpFs.getFileStatus(path); }
catch (IOException e) {
    if (!(e instanceof FileNotFoundException) && e.getCause() instanceof SftpException) { retryWithReconnect(path); }
    else throw e;
}

Prevention

When it happens

Trigger: Calling getFileStatus(path) while the SFTP channel has dropped or the server rejects the stat operation (SSH_FX_PERMISSION_DENIED, SSH_FX_FAILURE, connection reset), i.e. any SftpException whose id != SSH_FX_NO_SUCH_FILE.

Common situations: Long-running jobs where the SFTP session times out before the stat call; server-side permission restrictions on a directory; transient network failures mid-job.

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