{"record":{"id":"4d209340439fd085","repo":"apache/seatunnel","slug":"iotdbconnectorerrorcode-initialize-client-failed","errorCode":"IotdbConnectorErrorCode.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/src/main/java/org/apache/seatunnel/connectors/seatunnel/iotdb/sink/IoTDBSinkClient.java","lineNumber":86,"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(IoTDBRecord 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":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-iotdb/src/main/java/org/apache/seatunnel/connectors/seatunnel/iotdb/sink/IoTDBSinkClient.java#L68-L104","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the sink config node addresses and port (default 6667) and test connectivity: telnet/nc to host:6667","Validate username/password, e.g. with the IoTDB CLI (start-cli.sh -h host -p 6667 -u root -pw root)","Check IoTDB DataNode logs and status; restart or scale the cluster if down","Inspect the wrapped IoTDBConnectionException cause in SeaTunnel logs for the precise reason (refused vs auth vs timeout)","If transient (startup race), add retry/readiness checks so the job starts after IoTDB is healthy"],"exampleFix":"// before\nsink {\n  IoTDB {\n    node_urls = [\"127.0.0.1:6667\"]\n    username = \"root\"\n    password = \"wrong\"\n  }\n}\n// after\nsink {\n  IoTDB {\n    node_urls = [\"iotdb-datanode:6667\"]\n    username = \"root\"\n    password = \"root\"\n  }\n}","handlingStrategy":"retry","validationCode":"// before submitting the job\nProcess p = Runtime.getRuntime().exec(new String[]{\"/bin/sh\",\"-c\",\"nc -z -w 3 <iotdb-host> 6667 && echo OK || echo FAIL\"});\n// expect OK; also verify credentials via IoTDB CLI","typeGuard":"boolean sinkConfigValid(Map<String,Object> cfg) {\n    return cfg.get(\"node_urls\") != null && cfg.get(\"username\") != null && cfg.get(\"password\") != null;\n}","tryCatchPattern":"try {\n    sinkWriter.write(row);\n} catch (IotdbConnectorException e) {\n    if (e.getCode() == IotdbConnectorErrorCode.INITIALIZE_CLIENT_FAILED) {\n        log.error(\"Cannot connect to IoTDB at configured node_urls; cause: {}\", e.getCause());\n        // check network/credentials, then retry with backoff\n    } else { throw e; }\n}","preventionTips":["Verify node_urls, port (6667), username/password with the IoTDB CLI before submitting","Add IoTDB readiness checks/gates in deployment so jobs start only when DataNodes are up","Check container DNS/firewall rules between SeaTunnel workers and IoTDB nodes"],"tags":["iotdb","connection","sink","init"],"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"}