apache/seatunnel · error · HugeGraphConnectorException

GRAPH_OPERATION_FAILED

GRAPH_OPERATION_FAILED

Error message

Failed to split %s label '%s' into shards for a parallel (parallelism>1) read. Shard scans require a scan-capable HugeGraph backend (RocksDB/HBase/Cassandra); the in-memory backend does not support them. Set parallelism=1 to read via a single label-list scan instead.

What it means

HugeGraph connector throws this when a parallel read (parallelism>1) requires splitting a vertex/edge label into shards, but the backend rejects the vertexShards/edgeShards call. Shard scans only work on scan-capable backends (RocksDB, HBase, Cassandra); the in-memory (memory) backend does not support them. The original server error is preserved as the cause.

Solutions

Set parallelism=1 in the source config so reads use a single label-list scan instead of shard scans.
Switch the HugeGraph server to a scan-capable backend (RocksDB, HBase, or Cassandra) if parallel reads are required.
Inspect the wrapped cause (original RuntimeException) to confirm the backend limitation message.

Example fix

// before
parallelism = 4
// after
parallelism = 1

Defensive patterns

Strategy: fallback

Validate before calling

// before creating the source
boolean parallel = conf.getInteger("parallelism", 1) > 1;
String backend = hugeGraphClient.graphBackend(); // e.g. "memory", "rocksdb", "hbase", "cassandra"
if (parallel && "memory".equalsIgnoreCase(backend)) {
    conf.setInteger("parallelism", 1); // fall back to single label-list scan
}

Try / catch

try (HugeGraphSource source = buildSource(conf)) {
    source.open();
} catch (HugeGraphConnectorException e) {
    if (e.getCode() == GRAPH_OPERATION_FAILED && e.getCause() != null) {
        LOG.warn("Shard split failed on backend {}; retrying with parallelism=1", graphBackend(), e);
        conf.setInteger("parallelism", 1);
        source = buildSource(conf); source.open();
    } else { throw e; }
}

Prevention

Check the HugeGraph server's backend type before enabling parallel reads.
Keep parallelism=1 in dev/test environments using the in-memory backend.
Document the parallelism-vs-backend constraint in your job templates.
Log and inspect the cause to distinguish backend limits from transient server errors.

When it happens

Trigger: Calling source open -> discover with parallelism>1 against a HugeGraph server running the in-memory backend; the enumerator calls client.vertexShards(splitSize) or client.edgeShards(splitSize) and the server rejects it.

Common situations: Developers testing locally with HugeGraph's default in-memory backend but copying a parallel-read config (parallelism>1) from production docs; switching configs between environments without checking backend type.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-hugegraph/src/main/java/org/apache/seatunnel/connectors/seatunnel/hugegraph/source/HugeGraphSourceSplitEnumerator.java:172

        if (parallelism <= 1) {
            allSplits.add(
                    HugeGraphSourceSplit.labelListSplit("label-list", sourceConfig.getLabel()));
            LOG.info(
                    "HugeGraph source: parallelism=1, using single label-list split for label '{}'",
                    sourceConfig.getLabel());
            return;
        }
        boolean vertex = sourceConfig.getLabelType() == MappingConfig.LabelType.VERTEX;
        HugeGraphOperations client = clientFactory.get();
        List<Shard> shards;
        try {
            shards = vertex ? client.vertexShards(splitSize) : client.edgeShards(splitSize);
        } catch (RuntimeException e) {
            // Shard splitting is a scan-capable-backend feature. The in-memory backend rejects
            // vertexShards/edgeShards, and the raw server error gives the user no way forward, so
            // point them at the parallelism=1 label-list path (the original error is kept as
            // cause).
            throw new HugeGraphConnectorException(
                    HugeGraphConnectorErrorCode.GRAPH_OPERATION_FAILED,
                    String.format(
                            "Failed to split %s label '%s' into shards for a parallel (parallelism>1) "
                                    + "read. Shard scans require a scan-capable HugeGraph backend "
                                    + "(RocksDB/HBase/Cassandra); the in-memory backend does not "
                                    + "support them. Set parallelism=1 to read via a single "
                                    + "label-list scan instead.",
                            vertex ? "vertex" : "edge", sourceConfig.getLabel()),
                    e);
        } finally {
            client.close();
        }
        int index = 0;
        for (Shard shard : shards) {
            allSplits.add(HugeGraphSourceSplit.shardSplit("shard-" + index, shard));
            index++;
        }
        LOG.info(

View on GitHub (pinned to cf67b549a7)