apache/seatunnel · critical · NebulaGraphConnectorException

CONNECT_FAILED

CONNECT_FAILED

Error message

Unable to initialize a NebulaGraph session pool for space '${space}'.

What it means

SessionPoolNebulaGraphClient's constructor creates a NebulaGraph Java SessionPool. If SessionPool construction throws a RuntimeException (auth failure, unreachable graphd, bad space name), it is wrapped as NebulaGraphConnectorException with CONNECT_FAILED naming the configured space. The sink cannot operate without a valid session pool.

Solutions

Verify NebulaGraph hosts/ports are reachable (telnet/nc to graphd 9669)
Test credentials and space with nebula-console: USE <space>; run a trivial query
Confirm the space exists (SHOW SPACES) and the name matches config exactly
Check NebulaGraph service health (graphd/metad/storaged status) and retry

Example fix

// before
space = "my_Space"
// after (space must exist and match exactly)
space = "my_space"

Defensive patterns

Strategy: validation

Validate before calling

// preflight with nebula-console before running the job
// SHOW SPACES;            -> confirm space exists
// USE my_space; DESCRIBE TAG my_tag;  -> confirm schema
// also: nc -zv <graphd-host> 9669

Try / catch

try {
    client = new SessionPoolNebulaGraphClient(config);
} catch (NebulaGraphConnectorException e) {
    LOG.error("Session pool init failed for space {}. Check address/credentials/space.", space, e.getCause());
    throw e;
}

Prevention

Validate graphd address/port reachability before job start
Verify username/password against Nebula ACLs
CREATE SPACE and schema must exist before the sink runs
Space names are case-sensitive — match config exactly

When it happens

Trigger: new SessionPool(poolConfig) fails at writer init: wrong host/port, invalid username/password, space does not exist, or graph service unreachable.

Common situations: Typo in graphAddress/graphd host; NebulaGraph cluster down or still electing leaders; wrong credentials; space name mismatch (case-sensitive) or space not yet created with 'CREATE SPACE'.

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

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-nebulagraph/src/main/java/org/apache/seatunnel/connectors/seatunnel/nebulagraph/client/SessionPoolNebulaGraphClient.java:53

    public SessionPoolNebulaGraphClient(NebulaGraphSinkConfig config) {
        SessionPoolConfig poolConfig =
                new SessionPoolConfig(
                                config.getHosts(),
                                config.getSpace(),
                                config.getUsername(),
                                config.getPassword())
                        .setMinSessionSize(1)
                        .setMaxSessionSize(1)
                        .setTimeout(config.getTimeoutMillis())
                        .setWaitTime(config.getTimeoutMillis())
                        .setRetryTimes(config.getMaxRetries())
                        .setIntervalTime(
                                config.getMaxRetries() == 0 ? 0 : config.getRetryIntervalMillis())
                        .setReconnect(true);
        try {
            this.sessionPool = new SessionPool(poolConfig);
        } catch (RuntimeException e) {
            throw new NebulaGraphConnectorException(
                    NebulaGraphConnectorErrorCode.CONNECT_FAILED,
                    "Unable to initialize a NebulaGraph session pool for space '"
                            + config.getSpace()
                            + "'.",
                    e);
        }
    }

    @Override
    public void execute(String statement, Map<String, Object> parameters) throws IOException {
        try {
            ResultSet result = sessionPool.execute(statement, parameters);
            if (!result.isSucceeded()) {
                throw new IOException(
                        "NebulaGraph rejected the write with code "
                                + result.getErrorCode()
                                + ": "
                                + result.getErrorMessage());

View on GitHub (pinned to cf67b549a7)