What causes "Close IoTDB session failed" in apache/seatunnel?

Usually safe to ignore if all data was read; the session resources are released on the server by timeout

apache/seatunnel · warning · IotdbConnectorException

IotdbConnectorErrorCode.CLOSE_SESSION_FAILED

IotdbConnectorErrorCode.CLOSE_SESSION_FAILED

Error message

Close IoTDB session failed

What it means

Thrown by IoTDBv2SourceReader.close() when closing the IoTDB Session raises IoTDBConnectionException. The read itself already completed; this is a cleanup-path failure releasing the session back to the server. Since close() declares IOException, this error propagates to the reader lifecycle handling.

Source

Thrown at seatunnel-connectors-v2/connector-iotdb-v2/src/main/java/org/apache/seatunnel/connectors/seatunnel/iotdbv2/source/IoTDBv2SourceReader.java:69

            ReadonlyConfig conf, SourceReader.Context readerContext, SeaTunnelRowType rowType) {
        super(conf, readerContext);
        this.deserializer = new DefaultSeaTunnelRowDeserializer(rowType, SourceConstants.TREE);
    }

    @Override
    public void open() throws Exception {
        session = buildSession(conf);
        session.open();
    }

    @Override
    public void close() throws IOException {
        try {
            if (session != null) {
                session.close();
            }
        } catch (IoTDBConnectionException e) {
            throw new IotdbConnectorException(
                    IotdbConnectorErrorCode.CLOSE_SESSION_FAILED, "Close IoTDB session failed", e);
        }
    }

    private Session buildSession(ReadonlyConfig conf) {
        Session.Builder sessionBuilder = new Session.Builder();
        List<String> nodes = conf.get(NODE_URLS);
        sessionBuilder.nodeUrls(nodes);
        if (null != conf.get(FETCH_SIZE)) {
            sessionBuilder.fetchSize(Integer.parseInt(conf.get(FETCH_SIZE).toString()));
        }
        if (null != conf.get(USERNAME)) {
            sessionBuilder.username(conf.get(USERNAME));
        }
        if (null != conf.get(PASSWORD)) {
            sessionBuilder.password(conf.get(PASSWORD));
        }
        if (null != conf.get(DEFAULT_THRIFT_BUFFER_SIZE)) {

View on GitHub (pinned to cf67b549a7)

Solutions

Usually safe to ignore if all data was read; the session resources are released on the server by timeout
Check IoTDB server availability/logs if this appears alongside read failures
Ensure only one close() path exists (avoid double-close); guard with a flag if needed
Verify network stability between workers and IoTDB to reduce stale connections

Defensive patterns

Strategy: try-catch

Type guard

if (session == null) return; // nothing to close

Try / catch

try {
    reader.close();
} catch (IOException e) {
    if (e instanceof IotdbConnectorException
            && IotdbConnectorErrorCode.CLOSE_SESSION_FAILED.equals(((IotdbConnectorException) e).getSeaTunnelErrorCode())) {
        log.warn("Session close failed after read completion; resources will expire server-side", e);
    } else {
        throw e;
    }
}

Prevention

Treat close failures as non-fatal if all data was consumed and acked
Avoid double-closing sessions; track close state
Monitor IoTDB restarts/timeouts which leave stale sessions
Keep session idle/connection timeouts aligned between client and server

When it happens

Trigger: session.close() fails because the connection to IoTDB is already dead (server restarted, network drop, idle eviction), or the session was already closed elsewhere.

Common situations: Long-running job where IoTDB restarts or the connection times out before close; job cancellation after a network outage; IoTDB killed abruptly so the TCP close handshake fails.

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

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