apache/seatunnel · error · IOException

Generic exception wrapped (open failed)

Error message

Generic exception wrapped (open failed)

What it means

open() catches any Exception from the open/stream-creation sequence; non-IOException causes (e.g. SftpException escaping, NPE, pool errors) are wrapped into a new IOException. It is a catch-all indicating the open failed for a reason not covered by the specific checks (directory, missing file handled elsewhere).

Source

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

        try {
            Path workDir = new Path(channel.pwd());
            Path absolute = makeAbsolute(workDir, f);
            FileStatus fileStat = getFileStatus(channel, absolute);
            if (fileStat.isDirectory()) {
                throw new IOException(String.format(E_PATH_DIR, f));
            }
            // the path could be a symbolic link, so get the real path
            absolute = new Path("/", channel.realpath(absolute.toUri().getPath()));

            InputStream is = channel.get(quote(absolute.toUri().getPath()));
            return new FSDataInputStream(
                    new SFTPInputStream(is, channel, connectionPool, statistics));
        } catch (Exception e) {
            disconnectAfterFailure(channel, e);
            if (e instanceof IOException) {
                throw (IOException) e;
            }
            throw new IOException(e);
        }
    }

    /**
     * A stream obtained via this call must be closed before using other APIs of this class or else
     * the invocation will block.
     */
    @Override
    public FSDataOutputStream create(
            Path f,
            FsPermission permission,
            boolean overwrite,
            int bufferSize,
            short replication,
            long blockSize,
            Progressable progress)
            throws IOException {
        final ChannelSftp client = connect();

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Inspect the cause chain of the IOException to find the root exception
  2. Reconnect and retry the open (transient network issues are the most common cause)
  3. Validate the path (exists, is a file) before open to rule out precondition failures
  4. Check connection pool configuration/health if failures correlate with pool usage

Example fix

// before
FSDataInputStream in = fs.open(path);
// after
try {
    FSDataInputStream in = fs.open(path);
} catch (IOException e) {
    Throwable cause = e.getCause();
    // log cause, reconnect and retry once
    throw e;
}
Defensive patterns

Strategy: try-catch

Validate before calling

if (!fs.exists(path) || fs.getFileStatus(path).isDirectory()) {
    throw new IOException("Invalid open target: " + path);
}

Try / catch

try {
    FSDataInputStream in = fs.open(path);
} catch (IOException e) {
    // unwrap cause: SftpException -> reconnect/retry; other -> surface root cause
    Throwable c = e.getCause();
    if (c instanceof SftpException) { /* reconnect + retry once */ }
    throw e;
}

Prevention

When it happens

Trigger: fs.open() when channel.get() fails mid-call (connection dropped), connectionPool returns no channel, quote()/realpath throws unexpectedly, or any other non-IO runtime exception occurs before returning the SFTPInputStream.

Common situations: Transient network failures during file open; SFTP channel closed by server between exists-check and get; bugs such as malformed path characters causing unexpected exceptions; pool exhaustion misreported as generic failure.

Understand the failure class

Background: "open() failed", "failed to open file", "cannot create file" — what a file open error means and how to fix it — this error's family across 42 libraries.

Related errors

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