{"record":{"id":"d9bcfbdbe05a3685","repo":"apache/seatunnel","slug":"build-client-failed","errorCode":"BUILD_CLIENT_FAILED","errorMessage":"Failed to establish initial connection","messagePattern":"Failed to establish initial connection","errorType":"error_code","errorClass":"HugeGraphConnectorException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-hugegraph/src/main/java/org/apache/seatunnel/connectors/seatunnel/hugegraph/client/HugeGraphClient.java","lineNumber":138,"sourceCode":"\n    @FunctionalInterface\n    private interface ReadOperation<T> {\n        T execute() throws ServerException, ClientException;\n    }\n\n    private void ensureClientInitialized() throws HugeGraphConnectorException {\n        if (this.client == null) {\n            LOG.info(\"Client not initialized. Attempting to connect...\");\n            try {\n                this.client = createClient(this.config);\n                this.schema = this.client.schema();\n                createPageApis(this.config);\n                LOG.info(\"HugeClient initialized successfully.\");\n            } catch (Exception e) {\n                // Avoid leaking a partially-opened client (e.g. createPageApis failed after the\n                // HugeClient was created) — release everything before surfacing the failure.\n                reconnect();\n                throw new HugeGraphConnectorException(\n                        HugeGraphConnectorErrorCode.BUILD_CLIENT_FAILED,\n                        \"Failed to establish initial connection\",\n                        e);\n            }\n        }\n    }\n\n    private void reconnect() {\n        LOG.warn(\"Connection issue detected. Forcing reconnection...\");\n        if (this.client != null) {\n            try {\n                this.client.close();\n            } catch (Exception e) {\n                LOG.warn(\"Error closing potentially broken client: {}\", e.getMessage());\n            }\n        }\n        this.client = null;\n        if (this.restClient != null) {","sourceCodeStart":120,"sourceCodeEnd":156,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-hugegraph/src/main/java/org/apache/seatunnel/connectors/seatunnel/hugegraph/client/HugeGraphClient.java#L120-L156","documentation":"HugeGraphClient.ensureClientInitialized lazily creates the HugeClient and page APIs. If any step of initial client construction fails (connection, config, page API setup), the partially-open client is released via reconnect() and BUILD_CLIENT_FAILED is thrown with 'Failed to establish initial connection'.","triggerScenarios":"First write/read/schema call (executeNonIdempotentWrite, executeGraphOperation, executeReadOperation, getSchema) triggers lazy init; HugeClient.create fails due to unreachable host, wrong URL/port, bad credentials, or createPageApis fails after client creation.","commonSituations":"Wrong hugegraph host/port in sink config; server not started or behind firewall; wrong graph name; TLS/auth misconfiguration; version mismatch between client and server REST API.","solutions":["Verify the HugeGraph server is reachable: curl http://<host>:<port>/graphs/<graph>.","Check host, port, and graph name in the connector config.","Review the wrapped cause for whether it was a connect failure or createPageApis failure.","Confirm client/server HugeGraph versions are compatible."],"exampleFix":"// before\nHugeGraph {\n  host = \"10.0.0.5\"\n  port = 8080\n  graph = \"hugegraph\"\n}\n// after (host actually serving HugeGraph)\nHugeGraph {\n  host = \"hugegraph.svc.cluster.local\"\n  port = 8080\n  graph = \"hugegraph\"\n}","handlingStrategy":"try-catch","validationCode":"// pre-flight connectivity check\nHttpClient c = HttpClient.newHttpClient();\nHttpResponse<String> r = c.send(HttpRequest.newBuilder(URI.create(\"http://host:8080/graphs/hugegraph\")).GET().build(), BodyHandlers.ofString());\nif (r.statusCode() != 200) throw new IllegalStateException(\"HugeGraph unreachable\");","typeGuard":null,"tryCatchPattern":"try {\n    hugeGraphClient.getSchema();\n} catch (HugeGraphConnectorException e) {\n    if (e.getErrorCode() == HugeGraphConnectorErrorCode.BUILD_CLIENT_FAILED) {\n        LOG.error(\"cannot reach HugeGraph at {}:{}\", host, port, e.getCause());\n    }\n    throw e;\n}","preventionTips":["Run a connectivity smoke test on all worker nodes before submitting jobs.","Pin host/port/graph in config and verify with curl.","Confirm client and server version compatibility."],"tags":["hugegraph","connection","client-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-14T05:17:10.506Z"}