apache/seatunnel · error · IllegalArgumentException

SFTP client null or not connected

Error message

SFTP client null or not connected

What it means

The SFTPInputStream constructor throws IllegalArgumentException when the ChannelSftp is null or not connected, since reads require a live SFTP channel. This fails fast at construction rather than producing confusing read errors later.

Solutions

1. Obtain a connected channel from the SFTPConnectionPool (or connect it) before creating the stream.
2. Check channel.isConnected() before construction and reconnect if false.
3. Tune SFTP keep-alive/timeout settings to prevent idle disconnects in long jobs.
4. Verify connection pool configuration (max connections, idle eviction) is not closing channels prematurely.

Example fix

// before
SFTPInputStream s = new SFTPInputStream(in, staleChannel, pool, stats);
// after
if (channel == null || !channel.isConnected()) { channel = pool.connect(); }
SFTPInputStream s = new SFTPInputStream(in, channel, pool, stats);

if (channel == null || !channel.isConnected()) { channel = pool.connect(); }

boolean usable(ChannelSftp c) { return c != null && c.isConnected(); }

try { in = SFTPInputStream.getInstance(path, ...); }
catch (IllegalArgumentException e) { channel = pool.connect(); in = SFTPInputStream.getInstance(path, ...); }

When it happens

Trigger: Constructing SFTPInputStream (or calling its factory) with a channel that was never connected, or whose connection was dropped/closed by the pool or server before the stream is created.

Common situations: Reusing a pooled SFTP channel that the server already closed due to idle timeout; passing an unconnected ChannelSftp from custom code; connection pool exhausted/closed during job teardown.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• Null InputStream
• Seek not supported
• SFTP lstat failed for path=
• SFTP READDIR failed for path=
• SftpException wrapped (pwd failed while creating directory)

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

    private InputStream wrappedStream;
    private ChannelSftp channel;
    private SFTPConnectionPool connectionPool;
    private FileSystem.Statistics stats;
    private boolean closed;
    private long pos;

    SFTPInputStream(
            InputStream stream,
            ChannelSftp channel,
            SFTPConnectionPool connectionPool,
            FileSystem.Statistics stats) {

        if (stream == null) {
            throw new IllegalArgumentException(E_NULL_INPUT_STREAM);
        }
        if (channel == null || !channel.isConnected()) {
            throw new IllegalArgumentException(E_CLIENT_NULL);
        }
        this.wrappedStream = stream;
        this.channel = channel;
        this.connectionPool = connectionPool;
        this.stats = stats;

        this.pos = 0;
        this.closed = false;
    }

    @Override
    public void seek(long position) throws IOException {
        throw new IOException(E_SEEK_NOT_SUPPORTED);
    }

    @Override
    public boolean seekToNewSource(long targetPos) throws IOException {
        throw new IOException(E_SEEK_NOT_SUPPORTED);

View on GitHub (pinned to cf67b549a7)