apache/seatunnel · warning · IotdbConnectorException

IotdbConnectorErrorCode.CLOSE_SESSION_FAILED

IotdbConnectorErrorCode.CLOSE_SESSION_FAILED

Error message

Close IoTDB session failed

What it means

This error is thrown by IoTDBv2RelationalSourceReader.close() when the TableSession cannot be closed cleanly, i.e. tableSession.close() raises IoTDBConnectionException. It wraps the original exception with error code CLOSE_SESSION_FAILED. It usually indicates the connection to the IoTDB server was already broken (network drop, server restart, session timeout) rather than a problem with close() itself.

Source

Thrown at seatunnel-connectors-v2/connector-iotdb-v2/src/main/java/org/apache/seatunnel/connectors/seatunnel/iotdbv2/source/relational/IoTDBv2RelationalSourceReader.java:71

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

    @Override
    public void open() throws Exception {
        tableSession = buildTableSession(conf);
    }

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

    private ITableSession buildTableSession(ReadonlyConfig conf) throws IoTDBConnectionException {
        TableSessionBuilder sessionBuilder = new TableSessionBuilder().enableCompression(false);
        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(DATABASE)) {

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Check IoTDB server logs and availability at the time close() was called; the underlying cause is usually a broken connection, not close logic
  2. Verify network stability between the SeaTunnel worker and the IoTDB node(s) (firewall idle-connection timeouts, keepalive settings)
  3. Tune IoTDB session timeouts (e.g. enable_rpc_compression / session idle timeout) so idle sessions are not reaped during long reads
  4. If transient, retry the job; ensure the reader's close failure does not mask the original read error by inspecting the wrapped cause

Example fix

// before
try {
    if (tableSession != null) {
        tableSession.close();
    }
} catch (IoTDBConnectionException e) {
    throw new IotdbConnectorException(IotdbConnectorErrorCode.CLOSE_SESSION_FAILED, "Close IoTDB session failed", e);
}
// after
try {
    if (tableSession != null) {
        tableSession.close();
    }
} catch (IoTDBConnectionException e) {
    log.warn("IoTDB session already broken during close; cause: {}", e.getMessage());
    throw new IotdbConnectorException(IotdbConnectorErrorCode.CLOSE_SESSION_FAILED, "Close IoTDB session failed", e);
}
Defensive patterns

Strategy: try-catch

Validate before calling

// pre-check before job
Process p = Runtime.getRuntime().exec(new String[]{"/bin/sh","-c","nc -z -w 3 <iotdb-host> 6667 && echo OK || echo FAIL"});
// p.waitFor() output should be OK

Type guard

boolean sessionOpen(TableSession s) { return s != null; }

Try / catch

try { reader.close(); } catch (IotdbConnectorException e) {
    if (e.getCode() == IotdbConnectorErrorCode.CLOSE_SESSION_FAILED) {
        log.warn("IoTDB session close failed (likely already broken): {}", e.getCause());
    } else { throw e; }
}

Prevention

When it happens

Trigger: Calling close() on the source reader while tableSession != null and tableSession.close() throws IoTDBConnectionException — typically after the IoTDB server became unreachable, the session was already closed server-side, or a network partition occurred.

Common situations: IoTDB cluster restarted or failed over mid-job; idle session reaped by server timeout; firewall/NAT dropped the long-lived TCP connection during a long-running read; DNS/network change in Kubernetes environments.

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/cbb39c15b4edb8ce. Report an issue: GitHub.