{"record":{"id":"4dbb85c044da0b24","repo":"apache/seatunnel","slug":"initialize-client-failed","errorCode":"INITIALIZE_CLIENT_FAILED","errorMessage":"Initialize IoTDB client failed.","messagePattern":"Initialize IoTDB client failed\\.","errorType":"error_code","errorClass":"IotdbConnectorException","httpStatus":null,"severity":"critical","filePath":"seatunnel-connectors-v2/connector-iotdb-v2/src/main/java/org/apache/seatunnel/connectors/seatunnel/iotdbv2/sink/IoTDBv2SinkClient.java","lineNumber":85,"sourceCode":"        }\n        if (sinkConfig.getZoneId() != null) {\n            sessionBuilder.zoneId(sinkConfig.getZoneId());\n        }\n\n        session = sessionBuilder.build();\n        try {\n            if (sinkConfig.getConnectionTimeoutInMs() != null) {\n                session.open(\n                        sinkConfig.getEnableRPCCompression(),\n                        sinkConfig.getConnectionTimeoutInMs());\n            } else if (sinkConfig.getEnableRPCCompression() != null) {\n                session.open(sinkConfig.getEnableRPCCompression());\n            } else {\n                session.open();\n            }\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        initialize = true;\n    }\n\n    public synchronized void write(IoTDBv2Record record) throws IOException {\n        tryInit();\n        checkFlushException();\n\n        batchList.add(record);\n        if (sinkConfig.getBatchSize() > 0 && batchList.size() >= sinkConfig.getBatchSize()) {\n            flush();\n        }\n    }\n\n    public synchronized void close() throws IOException {","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-iotdb-v2/src/main/java/org/apache/seatunnel/connectors/seatunnel/iotdbv2/sink/IoTDBv2SinkClient.java#L67-L103","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify IoTDB is running and reachable: test with the IoTDB CLI or `nc -vz <host> 6667` from the SeaTunnel worker","Check sink options node_urls/username/password for correctness and test the same credentials with the IoTDB CLI","If enable_rpc_compression=true, set it false (or enable compression support on the IoTDB server) and retry","Inspect the wrapped IoTDBConnectionException cause in the stack trace — it distinguishes connection refused vs auth vs timeout","Check firewall/security-group rules between SeaTunnel workers and the IoTDB node"],"exampleFix":"// before\nnode_urls = \"wrong-host:6667\"\n// after\nnode_urls = \"iotdb-host:6667\"\nusername = \"root\"\npassword = \"root\"","handlingStrategy":"retry","validationCode":"try (Socket s = new Socket()) {\n    String[] hp = nodeUrl.split(\":\");\n    s.connect(new InetSocketAddress(hp[0], Integer.parseInt(hp[1])), 5000);\n} catch (IOException e) {\n    throw new IllegalStateException(\"IoTDB unreachable at \" + nodeUrl, e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    table.write(...);\n} catch (IotdbConnectorException e) {\n    if (e.getSeaTunnelErrorCode() == IotdbConnectorErrorCode.INITIALIZE_CLIENT_FAILED) {\n        // check host/port/credentials, then retry with backoff\n    }\n    throw e;\n}","preventionTips":["Pre-verify connectivity with the IoTDB CLI from every worker node","Double-check node_urls, username, password against a working CLI login","Only enable RPC compression if the IoTDB server supports it","Add readiness checks/alerting on the IoTDB service before submitting jobs"],"tags":["iotdb","connection","session","network"],"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"}