{"record":{"id":"aeba4ac8c332c90a","repo":"apache/seatunnel","slug":"initialize-client-failed-aeba4a","errorCode":"INITIALIZE_CLIENT_FAILED","errorMessage":"Initialize IoTDB client failed.","messagePattern":"Initialize IoTDB client failed\\.","errorType":"error_code","errorClass":"IotdbConnectorException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-iotdb-v2/src/main/java/org/apache/seatunnel/connectors/seatunnel/iotdbv2/sink/relational/IoTDBv2RelationalSinkClient.java","lineNumber":106,"sourceCode":"                        .enableCompression(false);\n        if (sinkConfig.getThriftDefaultBufferSize() != null) {\n            sessionBuilder.thriftDefaultBufferSize(sinkConfig.getThriftDefaultBufferSize());\n        }\n        if (sinkConfig.getThriftMaxFrameSize() != null) {\n            sessionBuilder.thriftMaxFrameSize(sinkConfig.getThriftMaxFrameSize());\n        }\n        if (sinkConfig.getZoneId() != null) {\n            sessionBuilder.zoneId(sinkConfig.getZoneId());\n        }\n        if (sinkConfig.getConnectionTimeoutInMs() != null) {\n            sessionBuilder.connectionTimeoutInMs(sinkConfig.getConnectionTimeoutInMs());\n        }\n\n        try {\n            tableSession = sessionBuilder.build();\n        } catch (IoTDBConnectionException e) {\n            log.error(\"Initialize IoTDB client failed.\", e);\n            throw new IotdbConnectorException(\n                    IotdbConnectorErrorCode.INITIALIZE_CLIENT_FAILED,\n                    \"Initialize IoTDB client failed.\",\n                    e);\n        }\n\n        try {\n            tableSession.executeNonQueryStatement(\"create database if not exists \" + database);\n        } catch (IoTDBConnectionException | StatementExecutionException e) {\n            log.error(\"Create database failed.\", e);\n            throw new IotdbConnectorException(\n                    IotdbConnectorErrorCode.INITIALIZE_CLIENT_FAILED,\n                    \"Initialize IoTDB client failed.\",\n                    e);\n        }\n\n        initialize = true;\n        curBatchSize = 0;\n    }","sourceCodeStart":88,"sourceCodeEnd":124,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-iotdb-v2/src/main/java/org/apache/seatunnel/connectors/seatunnel/iotdbv2/sink/relational/IoTDBv2RelationalSinkClient.java#L88-L124","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify node_urls, host and port in the sink config are reachable (telnet/nc to the IoTDB RPC port, default 6667)","Check IoTDB server is running and logs show the RPC service bound","Validate username/password with a CLI login (start-cli.sh -h host -p 6667 -u root -pw root)","Check network/firewall/DNS from the SeaTunnel worker nodes to the IoTDB nodes","Verify the IoTDB client version on the classpath matches the server version"],"exampleFix":"// before\nnode_urls = [\"localhost:6667\"]\n// after\nnode_urls = [\"iotdb-host:6667\"]  // reachable DNS name or IP, correct RPC port","handlingStrategy":"retry","validationCode":"// pre-flight check\nProcess p = new ProcessBuilder(\"nc\",\"-z\",\"iotdb-host\",\"6667\").start();\nboolean reachable = p.waitFor(3, TimeUnit.SECONDS) && p.exitValue() == 0;\nif (!reachable) throw new IllegalStateException(\"IoTDB host:port unreachable\");","typeGuard":null,"tryCatchPattern":"try {\n    client.tryInit();\n} catch (IotdbConnectorException e) {\n    if (IotdbConnectorErrorCode.INITIALIZE_CLIENT_FAILED.equals(e.getSeaTunnelErrorCode())) {\n        // exponential backoff reconnect / alert operator\n    }\n}","preventionTips":["Validate node_urls with a connectivity probe before job start","Confirm IoTDB credentials via CLI before deployment","Use DNS/service names that survive pod rescheduling","Keep IoTDB client jar version aligned with server version"],"tags":["iotdb","network","connection","session"],"backgroundTag":"connection-refused","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}