apache/seatunnel · error · HugeGraphConnectorException

BUILD_CLIENT_FAILED

BUILD_CLIENT_FAILED

Error message

Failed to establish initial connection

What it means

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'.

Source

Thrown at seatunnel-connectors-v2/connector-hugegraph/src/main/java/org/apache/seatunnel/connectors/seatunnel/hugegraph/client/HugeGraphClient.java:138

    @FunctionalInterface
    private interface ReadOperation<T> {
        T execute() throws ServerException, ClientException;
    }

    private void ensureClientInitialized() throws HugeGraphConnectorException {
        if (this.client == null) {
            LOG.info("Client not initialized. Attempting to connect...");
            try {
                this.client = createClient(this.config);
                this.schema = this.client.schema();
                createPageApis(this.config);
                LOG.info("HugeClient initialized successfully.");
            } catch (Exception e) {
                // Avoid leaking a partially-opened client (e.g. createPageApis failed after the
                // HugeClient was created) — release everything before surfacing the failure.
                reconnect();
                throw new HugeGraphConnectorException(
                        HugeGraphConnectorErrorCode.BUILD_CLIENT_FAILED,
                        "Failed to establish initial connection",
                        e);
            }
        }
    }

    private void reconnect() {
        LOG.warn("Connection issue detected. Forcing reconnection...");
        if (this.client != null) {
            try {
                this.client.close();
            } catch (Exception e) {
                LOG.warn("Error closing potentially broken client: {}", e.getMessage());
            }
        }
        this.client = null;
        if (this.restClient != null) {

View on GitHub (pinned to cf67b549a7)

Solutions

1. Verify the HugeGraph server is reachable: curl http://<host>:<port>/graphs/<graph>.
2. Check host, port, and graph name in the connector config.
3. Review the wrapped cause for whether it was a connect failure or createPageApis failure.
4. Confirm client/server HugeGraph versions are compatible.

Example fix

// before
HugeGraph {
  host = "10.0.0.5"
  port = 8080
  graph = "hugegraph"
}
// after (host actually serving HugeGraph)
HugeGraph {
  host = "hugegraph.svc.cluster.local"
  port = 8080
  graph = "hugegraph"
}

// pre-flight connectivity check
HttpClient c = HttpClient.newHttpClient();
HttpResponse<String> r = c.send(HttpRequest.newBuilder(URI.create("http://host:8080/graphs/hugegraph")).GET().build(), BodyHandlers.ofString());
if (r.statusCode() != 200) throw new IllegalStateException("HugeGraph unreachable");

try {
    hugeGraphClient.getSchema();
} catch (HugeGraphConnectorException e) {
    if (e.getErrorCode() == HugeGraphConnectorErrorCode.BUILD_CLIENT_FAILED) {
        LOG.error("cannot reach HugeGraph at {}:{}", host, port, e.getCause());
    }
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

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

• HugeGraph connection failed on attempt {}/{}. Error: {}
• CONNECTION_FAILED
• CONNECTION_FAILED
• Connection issue detected. Forcing reconnection...
• Error closing potentially broken client: {}

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