apache/seatunnel · error · IotdbConnectorException

INITIALIZE_CLIENT_FAILED

INITIALIZE_CLIENT_FAILED

Error message

Initialize IoTDB client failed.

What it means

Thrown by IoTDBv2RelationalSinkClient.tryInit when building the IoTDB table session fails with an IoTDBConnectionException. It means the sink could not establish a connection to the IoTDB server before any write occurred. This is a session-level connectivity/credential failure, not a query failure.

Source

Thrown at seatunnel-connectors-v2/connector-iotdb-v2/src/main/java/org/apache/seatunnel/connectors/seatunnel/iotdbv2/sink/relational/IoTDBv2RelationalSinkClient.java:106

                        .enableCompression(false);
        if (sinkConfig.getThriftDefaultBufferSize() != null) {
            sessionBuilder.thriftDefaultBufferSize(sinkConfig.getThriftDefaultBufferSize());
        }
        if (sinkConfig.getThriftMaxFrameSize() != null) {
            sessionBuilder.thriftMaxFrameSize(sinkConfig.getThriftMaxFrameSize());
        }
        if (sinkConfig.getZoneId() != null) {
            sessionBuilder.zoneId(sinkConfig.getZoneId());
        }
        if (sinkConfig.getConnectionTimeoutInMs() != null) {
            sessionBuilder.connectionTimeoutInMs(sinkConfig.getConnectionTimeoutInMs());
        }

        try {
            tableSession = sessionBuilder.build();
        } catch (IoTDBConnectionException e) {
            log.error("Initialize IoTDB client failed.", e);
            throw new IotdbConnectorException(
                    IotdbConnectorErrorCode.INITIALIZE_CLIENT_FAILED,
                    "Initialize IoTDB client failed.",
                    e);
        }

        try {
            tableSession.executeNonQueryStatement("create database if not exists " + database);
        } catch (IoTDBConnectionException | StatementExecutionException e) {
            log.error("Create database failed.", e);
            throw new IotdbConnectorException(
                    IotdbConnectorErrorCode.INITIALIZE_CLIENT_FAILED,
                    "Initialize IoTDB client failed.",
                    e);
        }

        initialize = true;
        curBatchSize = 0;
    }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Verify node_urls, host and port in the sink config are reachable (telnet/nc to the IoTDB RPC port, default 6667)
2. Check IoTDB server is running and logs show the RPC service bound
3. Validate username/password with a CLI login (start-cli.sh -h host -p 6667 -u root -pw root)
4. Check network/firewall/DNS from the SeaTunnel worker nodes to the IoTDB nodes
5. Verify the IoTDB client version on the classpath matches the server version

Example fix

// before
node_urls = ["localhost:6667"]
// after
node_urls = ["iotdb-host:6667"]  // reachable DNS name or IP, correct RPC port

// pre-flight check
Process p = new ProcessBuilder("nc","-z","iotdb-host","6667").start();
boolean reachable = p.waitFor(3, TimeUnit.SECONDS) && p.exitValue() == 0;
if (!reachable) throw new IllegalStateException("IoTDB host:port unreachable");

try {
    client.tryInit();
} catch (IotdbConnectorException e) {
    if (IotdbConnectorErrorCode.INITIALIZE_CLIENT_FAILED.equals(e.getSeaTunnelErrorCode())) {
        // exponential backoff reconnect / alert operator
    }
}

When it happens

Trigger: SessionPool/Session builder fails on sessionBuilder.build() or first interaction because nodeUrls are wrong/unreachable, username/password is incorrect, IoTDB is down, network/firewall blocks port 6667, or TLS settings mismatch.

Common situations: Wrong host/port in sink config (node_urls), IoTDB not yet started when the job launches, wrong username/password after a credential rotation, Docker/K8s networking where localhost does not reach IoTDB, cluster in read-only or shutting-down state.

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