apache/seatunnel · critical · IotdbConnectorException

IotdbConnectorErrorCode.INITIALIZE_CLIENT_FAILED

IotdbConnectorErrorCode.INITIALIZE_CLIENT_FAILED

Error message

Initialize IoTDB client failed.

What it means

IoTDBSinkClient.tryInit() (called lazily from write()) opens an IoTDB Session; if session.open() throws IoTDBConnectionException the client logs and rethrows INITIALIZE_CLIENT_FAILED. This means the sink could not establish a connection/session with the IoTDB server at the configured node URLs with the given credentials.

Source

Thrown at seatunnel-connectors-v2/connector-iotdb/src/main/java/org/apache/seatunnel/connectors/seatunnel/iotdb/sink/IoTDBSinkClient.java:86

        }
        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(IoTDBRecord 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 the sink config node addresses and port (default 6667) and test connectivity: telnet/nc to host:6667
2. Validate username/password, e.g. with the IoTDB CLI (start-cli.sh -h host -p 6667 -u root -pw root)
3. Check IoTDB DataNode logs and status; restart or scale the cluster if down
4. Inspect the wrapped IoTDBConnectionException cause in SeaTunnel logs for the precise reason (refused vs auth vs timeout)
5. If transient (startup race), add retry/readiness checks so the job starts after IoTDB is healthy

Example fix

// before
sink {
  IoTDB {
    node_urls = ["127.0.0.1:6667"]
    username = "root"
    password = "wrong"
  }
}
// after
sink {
  IoTDB {
    node_urls = ["iotdb-datanode:6667"]
    username = "root"
    password = "root"
  }
}

// before submitting the job
Process p = Runtime.getRuntime().exec(new String[]{"/bin/sh","-c","nc -z -w 3 <iotdb-host> 6667 && echo OK || echo FAIL"});
// expect OK; also verify credentials via IoTDB CLI

boolean sinkConfigValid(Map<String,Object> cfg) {
    return cfg.get("node_urls") != null && cfg.get("username") != null && cfg.get("password") != null;
}

try {
    sinkWriter.write(row);
} catch (IotdbConnectorException e) {
    if (e.getCode() == IotdbConnectorErrorCode.INITIALIZE_CLIENT_FAILED) {
        log.error("Cannot connect to IoTDB at configured node_urls; cause: {}", e.getCause());
        // check network/credentials, then retry with backoff
    } else { throw e; }
}

When it happens

Trigger: First write() triggers tryInit(); session.open() fails because the node host/port is wrong or unreachable, credentials are rejected, the server is down, or RPC compression setting mismatches.

Common situations: Wrong node_urls / host:port in sink config; IoTDB DataNode not started or behind a firewall; wrong username/password; Kerberos/ACL enabled but plain auth configured; DNS resolution failure in containerized deployments.

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

• CONNECT_FAILED
• INITIALIZE_CLIENT_FAILED
• INITIALIZE_CLIENT_FAILED
• IotdbConnectorErrorCode.CLOSE_SESSION_FAILED
• IotdbConnectorErrorCode.CLOSE_CLIENT_FAILED

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