apache/seatunnel · error · IOException

File check failed

Error message

File check failed

What it means

isFile() returns true only if the path exists and is not a directory; a FileNotFoundException yields false (treated as 'not a file'). Any other IOException from the underlying getFileStatus (broken channel, pwd/ls failures) is rethrown wrapped as 'File check failed'. It means the file-type check itself could not be completed due to an SFTP communication error.

Solutions

1. Reconnect the SFTP channel before retrying mkdirs/isFile
2. Check permissions on all ancestor directories of the path
3. Resolve or remove broken symlinks on the path
4. Inspect ioe.getCause() for the underlying SftpException id
5. Add SSH keepalive to prevent idle session drops during long jobs

Example fix

// before
fs.mkdirs(new Path("/data/out")); // isFile check throws 'File check failed'
// after
try {
    fs.mkdirs(new Path("/data/out"));
} catch (IOException e) {
    LOG.warn("mkdirs failed", e);
    reconnect(); // refresh SFTP channel
    fs.mkdirs(new Path("/data/out"));
}

if (channel == null || !channel.isConnected()) { channel = openConnectedChannel(conf); } // plus server-side: find /data -type l (audit symlinks)

try { fs.mkdirs(p); } catch (IOException e) { if (e.getMessage() != null && e.getMessage().contains("File check failed")) { reconnect(); fs.mkdirs(p); } else { throw e; } }

When it happens

Trigger: isFile() (called from mkdirs to detect path-type conflicts) hits a non-FNFE IOException from getFileStatus — e.g. dead channel, pwd rejected, symlink resolution failure.

Common situations: SFTP session dropped during a directory-creation sequence; symlinked output paths failing to resolve; permission problems on ancestor directories surfacing as IO (not FNFE) errors.

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

• Failed to get file status
• Can't make directory for path
• Can't make directory for path
• Close file output stream
• Close file output stream

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/07508ea461390790. 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:345

            }
        } else if (isFile(client, absolute)) {
            throw new IOException(String.format(E_DIR_CREATE_FROMFILE, absolute));
        } else {
            LOG.debug("Skipping creation of existing directory " + file);
        }
        if (!created) {
            LOG.debug("Failed to create " + file);
        }
        return created;
    }

    private boolean isFile(ChannelSftp channel, Path file) throws IOException {
        try {
            return !getFileStatus(channel, file).isDirectory();
        } catch (FileNotFoundException e) {
            return false; // file does not exist
        } catch (IOException ioe) {
            throw new IOException(E_FILE_CHECK_FAILED, ioe);
        }
    }

    /**
     * Convenience method, so that we don't open a new connection when using this method from within
     * another method. Otherwise every API invocation incurs the overhead of opening/closing a TCP
     * connection.
     */
    private boolean delete(ChannelSftp channel, Path file, boolean recursive) throws IOException {
        Path workDir;
        try {
            workDir = new Path(channel.pwd());
        } catch (SftpException e) {
            throw new IOException(e);
        }
        Path absolute = makeAbsolute(workDir, file);
        String pathName = absolute.toUri().getPath();
        FileStatus fileStat = null;

View on GitHub (pinned to cf67b549a7)