{"record":{"id":"13dbf9315d7dd6f9","repo":"apache/seatunnel","slug":"generic-exception-wrapped-open-failed","errorCode":null,"errorMessage":"Generic exception wrapped (open failed)","messagePattern":"Generic exception wrapped \\(open failed\\)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-file/connector-file-sftp/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/sftp/system/SFTPFileSystem.java","lineNumber":502,"sourceCode":"        try {\n            Path workDir = new Path(channel.pwd());\n            Path absolute = makeAbsolute(workDir, f);\n            FileStatus fileStat = getFileStatus(channel, absolute);\n            if (fileStat.isDirectory()) {\n                throw new IOException(String.format(E_PATH_DIR, f));\n            }\n            // the path could be a symbolic link, so get the real path\n            absolute = new Path(\"/\", channel.realpath(absolute.toUri().getPath()));\n\n            InputStream is = channel.get(quote(absolute.toUri().getPath()));\n            return new FSDataInputStream(\n                    new SFTPInputStream(is, channel, connectionPool, statistics));\n        } catch (Exception e) {\n            disconnectAfterFailure(channel, e);\n            if (e instanceof IOException) {\n                throw (IOException) e;\n            }\n            throw new IOException(e);\n        }\n    }\n\n    /**\n     * A stream obtained via this call must be closed before using other APIs of this class or else\n     * the invocation will block.\n     */\n    @Override\n    public FSDataOutputStream create(\n            Path f,\n            FsPermission permission,\n            boolean overwrite,\n            int bufferSize,\n            short replication,\n            long blockSize,\n            Progressable progress)\n            throws IOException {\n        final ChannelSftp client = connect();","sourceCodeStart":484,"sourceCodeEnd":520,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-file/connector-file-sftp/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/sftp/system/SFTPFileSystem.java#L484-L520","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the cause chain of the IOException to find the root exception","Reconnect and retry the open (transient network issues are the most common cause)","Validate the path (exists, is a file) before open to rule out precondition failures","Check connection pool configuration/health if failures correlate with pool usage"],"exampleFix":"// before\nFSDataInputStream in = fs.open(path);\n// after\ntry {\n    FSDataInputStream in = fs.open(path);\n} catch (IOException e) {\n    Throwable cause = e.getCause();\n    // log cause, reconnect and retry once\n    throw e;\n}","handlingStrategy":"try-catch","validationCode":"if (!fs.exists(path) || fs.getFileStatus(path).isDirectory()) {\n    throw new IOException(\"Invalid open target: \" + path);\n}","typeGuard":null,"tryCatchPattern":"try {\n    FSDataInputStream in = fs.open(path);\n} catch (IOException e) {\n    // unwrap cause: SftpException -> reconnect/retry; other -> surface root cause\n    Throwable c = e.getCause();\n    if (c instanceof SftpException) { /* reconnect + retry once */ }\n    throw e;\n}","preventionTips":["Unwrap getCause() to see the real failure","Retry transient failures with backoff","Check connection pool health/config","Validate path preconditions before open"],"tags":["sftp","io","open"],"backgroundTag":"file-open-failed","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}