{"record":{"id":"90a1942cbab7d352","repo":"apache/seatunnel","slug":"graph-operation-failed-90a194","errorCode":"GRAPH_OPERATION_FAILED","errorMessage":"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.","messagePattern":"Failed to split (.+?) label '(.+?)' 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\\.","errorType":"error_code","errorClass":"HugeGraphConnectorException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-hugegraph/src/main/java/org/apache/seatunnel/connectors/seatunnel/hugegraph/source/HugeGraphSourceSplitEnumerator.java","lineNumber":172,"sourceCode":"        if (parallelism <= 1) {\n            allSplits.add(\n                    HugeGraphSourceSplit.labelListSplit(\"label-list\", sourceConfig.getLabel()));\n            LOG.info(\n                    \"HugeGraph source: parallelism=1, using single label-list split for label '{}'\",\n                    sourceConfig.getLabel());\n            return;\n        }\n        boolean vertex = sourceConfig.getLabelType() == MappingConfig.LabelType.VERTEX;\n        HugeGraphOperations client = clientFactory.get();\n        List<Shard> shards;\n        try {\n            shards = vertex ? client.vertexShards(splitSize) : client.edgeShards(splitSize);\n        } catch (RuntimeException e) {\n            // Shard splitting is a scan-capable-backend feature. The in-memory backend rejects\n            // vertexShards/edgeShards, and the raw server error gives the user no way forward, so\n            // point them at the parallelism=1 label-list path (the original error is kept as\n            // cause).\n            throw new HugeGraphConnectorException(\n                    HugeGraphConnectorErrorCode.GRAPH_OPERATION_FAILED,\n                    String.format(\n                            \"Failed to split %s label '%s' into shards for a parallel (parallelism>1) \"\n                                    + \"read. Shard scans require a scan-capable HugeGraph backend \"\n                                    + \"(RocksDB/HBase/Cassandra); the in-memory backend does not \"\n                                    + \"support them. Set parallelism=1 to read via a single \"\n                                    + \"label-list scan instead.\",\n                            vertex ? \"vertex\" : \"edge\", sourceConfig.getLabel()),\n                    e);\n        } finally {\n            client.close();\n        }\n        int index = 0;\n        for (Shard shard : shards) {\n            allSplits.add(HugeGraphSourceSplit.shardSplit(\"shard-\" + index, shard));\n            index++;\n        }\n        LOG.info(","sourceCodeStart":154,"sourceCodeEnd":190,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-hugegraph/src/main/java/org/apache/seatunnel/connectors/seatunnel/hugegraph/source/HugeGraphSourceSplitEnumerator.java#L154-L190","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nparallelism = 4\n// after\nparallelism = 1","handlingStrategy":"fallback","validationCode":"// before creating the source\nboolean parallel = conf.getInteger(\"parallelism\", 1) > 1;\nString backend = hugeGraphClient.graphBackend(); // e.g. \"memory\", \"rocksdb\", \"hbase\", \"cassandra\"\nif (parallel && \"memory\".equalsIgnoreCase(backend)) {\n    conf.setInteger(\"parallelism\", 1); // fall back to single label-list scan\n}","typeGuard":null,"tryCatchPattern":"try (HugeGraphSource source = buildSource(conf)) {\n    source.open();\n} catch (HugeGraphConnectorException e) {\n    if (e.getCode() == GRAPH_OPERATION_FAILED && e.getCause() != null) {\n        LOG.warn(\"Shard split failed on backend {}; retrying with parallelism=1\", graphBackend(), e);\n        conf.setInteger(\"parallelism\", 1);\n        source = buildSource(conf); source.open();\n    } else { throw e; }\n}","preventionTips":["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."],"tags":["hugegraph","parallelism","shard-scan","backend-compatibility"],"backgroundTag":"unsupported-operation","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}