apache/seatunnel · error · IOException

Failed to get file status

Error message

Failed to get file status

What it means

SFTPFileSystem.exists() resolves a path via getFileStatus(); a FileNotFoundException means the path genuinely does not exist (returns false), but any other IOException from the SFTP layer (connection issues, SftpException on pwd/ls/stat) is rethrown wrapped as 'Failed to get file status'. It signals the caller could not determine existence due to an SFTP communication problem, not that the file is absent.

Solutions

  1. Verify the SFTP connection is still alive and reconnect if the session was dropped
  2. Check that the SFTP user has read/execute permission on the parent directory of the path
  3. Test pwd()/ls() manually with an sftp client using the same credentials to reproduce the failure
  4. Wrap long-running jobs with periodic keepalive or re-establish the FileSystem connection before exists()
  5. Inspect the wrapped cause (ioe.getCause()) to identify the exact SftpException id

Example fix

// before
boolean ok = fs.exists(path); // throws IOException 'Failed to get file status'
// after
boolean ok;
try {
    ok = fs.exists(path);
} catch (IOException e) {
    LOG.warn("Existence check failed, reconnecting", e);
    fs = reconnectFileSystem(conf); // re-open SFTP connection
    ok = fs.exists(path);
}
Defensive patterns

Strategy: try-catch

Validate before calling

if (channel == null || !channel.isConnected()) { channel = reconnect(conf); }

Try / catch

try { boolean ok = fs.exists(path); } catch (IOException e) { LOG.error("SFTP status check failed for {}", path, e); throw new UncheckedIOException(e); }

Prevention

When it happens

Trigger: exists() is called (directly or via mkdirs, rename, create) while the SFTP channel is broken/disconnected, the server rejects the pwd() command, or the underlying stat/ls raises a non-FileNotFound SftpException (e.g. permission failure).

Common situations: SFTP session dropped mid-job after network hiccup or server idle timeout; user lacks permission to list the parent directory; wrong working directory after cd; SSH server intermittently closing channels.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

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

Appendix: source

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

        connectionPool.disconnect(channel);
    }

    private Path makeAbsolute(Path workDir, Path path) {
        if (path.isAbsolute()) {
            return path;
        }
        return new Path(workDir, path);
    }

    private boolean exists(ChannelSftp channel, Path file) throws IOException {
        try {
            getFileStatus(channel, file);
            return true;
        } catch (FileNotFoundException fnfe) {
            LOG.debug("File does not exist: " + file, fnfe);
            return false;
        } catch (IOException ioe) {
            throw new IOException(E_FILE_STATUS, ioe);
        }
    }

    public String quote(String path) {
        byte[] _path = path.getBytes(StandardCharsets.UTF_8);
        int count = 0;
        for (int i = 0; i < _path.length; i++) {
            byte b = _path[i];
            if (b == '\\' || b == '?' || b == '*') {
                count++;
            }
        }
        if (count == 0) {
            return path;
        }
        byte[] _path2 = new byte[_path.length + count];
        for (int i = 0, j = 0; i < _path.length; i++) {
            byte b = _path[i];

View on GitHub (pinned to cf67b549a7)