apache/seatunnel · error · FTPException

File check failed

Error message

File check failed

What it means

isFile(FTPClient, Path) delegates to getFileStatus to determine if a path is a regular file. If getFileStatus fails with a generic IOException (not FileNotFoundException, which is treated as 'does not exist'), the method wraps it in an FTPException with the message 'File check failed' and the original cause attached.

Source

Thrown at seatunnel-connectors-v2/connector-file/connector-file-ftp/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/ftp/system/SeaTunnelFTPFileSystem.java:781

                                client.getReplyCode(),
                                client.getReplyString()));
            }
        }
        return true;
    }

    /**
     * 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 isFile(FTPClient client, Path file) {
        try {
            return getFileStatus(client, file).isFile();
        } catch (FileNotFoundException e) {
            return false; // file does not exist
        } catch (IOException ioe) {
            throw new FTPException("File check failed", ioe);
        }
    }

    /*
     * Assuming that parent of both source and destination is the same. Is the
     * assumption correct or it is supposed to work like 'move' ?
     */
    @Override
    public boolean rename(Path src, Path dst) throws IOException {
        FTPClient client = connect();
        try {
            boolean success = rename(client, src, dst);
            return success;
        } finally {
            disconnect(client);
        }
    }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Inspect the wrapped cause (ioe.getCause()) for the actual FTP/network failure
2. Verify FTP server availability and increase ftp connect/timeout settings in the connector config
3. Enable FTPClient passive mode if behind NAT/firewall
4. Retry the job — transient connection resets are common on unstable networks
5. Check server-side logs for session drops (idle timeout, max connections limit reached)

Example fix

// before
try {
    boolean isFile = fs.isFile(path);
} catch (FTPException e) { log.error("failed", e); }
// after
try {
    boolean isFile = fs.isFile(path);
} catch (FTPException e) {
    log.error("File check failed, FTP cause: {}", e.getCause(), e);
    // reconnect and retry before failing the job
}

// Java: check connectivity before file operations
FTPClient c = connect();
if (!FTPReply.isPositiveCompletion(c.getReplyCode())) {
    throw new IllegalStateException("FTP not ready: " + c.getReplyString());
}

try {
    boolean isFile = fs.isFile(path);
} catch (FTPException e) {
    logger.error("FTP file check failed; root cause: {}", e.getCause(), e);
    // reconnect and retry once for transient IO errors
}

When it happens

Trigger: Any IOException other than FileNotFoundException thrown by getFileStatus(client, file) during isFile — e.g. FTP connection reset mid-operation, socket timeout, or unexpected server reply — while checking whether a path is a file.

Common situations: FTP connection dropped or timed out between operations; server returned an unexpected reply code; network interruption during long-running sink/source jobs; FTP control channel in a bad state after a failed transfer.

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

• Unable to open file: ${file}, Aborting
• Client not connected
• Unable to create file: ${file}, Aborting
• Directory: ${file} is not empty.
• Failed to create directory %s in %s, FTP reply code: %d, rep

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