apache/seatunnel · critical · IotdbConnectorException

INITIALIZE_CLIENT_FAILED

INITIALIZE_CLIENT_FAILED

Error message

Initialize IoTDB client failed.

What it means

IoTDBv2SinkClient.tryInit() opens the IoTDB Session before writing. If session.open() (optionally with RPC compression enabled) throws IoTDBConnectionException, the client logs and wraps it in IotdbConnectorException with IotdbConnectorErrorCode.INITIALIZE_CLIENT_FAILED. It means the sink could not establish a working connection/session to the IoTDB server at all.

Source

Thrown at seatunnel-connectors-v2/connector-iotdb-v2/src/main/java/org/apache/seatunnel/connectors/seatunnel/iotdbv2/sink/IoTDBv2SinkClient.java:85

        }
        if (sinkConfig.getZoneId() != null) {
            sessionBuilder.zoneId(sinkConfig.getZoneId());
        }

        session = sessionBuilder.build();
        try {
            if (sinkConfig.getConnectionTimeoutInMs() != null) {
                session.open(
                        sinkConfig.getEnableRPCCompression(),
                        sinkConfig.getConnectionTimeoutInMs());
            } else if (sinkConfig.getEnableRPCCompression() != null) {
                session.open(sinkConfig.getEnableRPCCompression());
            } else {
                session.open();
            }
        } catch (IoTDBConnectionException e) {
            log.error("Initialize IoTDB client failed.", e);
            throw new IotdbConnectorException(
                    IotdbConnectorErrorCode.INITIALIZE_CLIENT_FAILED,
                    "Initialize IoTDB client failed.",
                    e);
        }
        initialize = true;
    }

    public synchronized void write(IoTDBv2Record record) throws IOException {
        tryInit();
        checkFlushException();

        batchList.add(record);
        if (sinkConfig.getBatchSize() > 0 && batchList.size() >= sinkConfig.getBatchSize()) {
            flush();
        }
    }

    public synchronized void close() throws IOException {

View on GitHub (pinned to cf67b549a7)

Solutions

1. Verify IoTDB is running and reachable: test with the IoTDB CLI or `nc -vz <host> 6667` from the SeaTunnel worker
2. Check sink options node_urls/username/password for correctness and test the same credentials with the IoTDB CLI
3. If enable_rpc_compression=true, set it false (or enable compression support on the IoTDB server) and retry
4. Inspect the wrapped IoTDBConnectionException cause in the stack trace — it distinguishes connection refused vs auth vs timeout
5. Check firewall/security-group rules between SeaTunnel workers and the IoTDB node

Example fix

// before
node_urls = "wrong-host:6667"
// after
node_urls = "iotdb-host:6667"
username = "root"
password = "root"

try (Socket s = new Socket()) {
    String[] hp = nodeUrl.split(":");
    s.connect(new InetSocketAddress(hp[0], Integer.parseInt(hp[1])), 5000);
} catch (IOException e) {
    throw new IllegalStateException("IoTDB unreachable at " + nodeUrl, e);
}

try {
    table.write(...);
} catch (IotdbConnectorException e) {
    if (e.getSeaTunnelErrorCode() == IotdbConnectorErrorCode.INITIALIZE_CLIENT_FAILED) {
        // check host/port/credentials, then retry with backoff
    }
    throw e;
}

When it happens

Trigger: First write attempt triggers tryInit; session.open() fails due to unreachable host:port, wrong node_urls, authentication failure (user/password), TLS/compression mismatch, or IoTDB not running / rejecting the session.

Common situations: IoTDB server down or firewalled; wrong host/port in sink config (default 6667); wrong username/password; enable_rpc_compression=true while the server lacks compression support; DNS/seed-node misconfiguration in a cluster.

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

• INITIALIZE_CLIENT_FAILED
• CREATE_ACTIVEMQ_CLIENT_FAILED
• CONNECTION_FAILED
• CONNECTION_FAILED
• Timed out after <actualSeconds> seconds while waiting to con

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