{"record":{"id":"fe037fc778b051b7","repo":"apache/seatunnel","slug":"illegal-config-argument-fe037f","errorCode":"ILLEGAL_CONFIG_ARGUMENT","errorMessage":"HugeGraph source 'filter' cannot be combined with parallelism > 1 (runtime parallelism is %d): parallel reads use shard key-range scans that do not support server-side property filtering. Either set parallelism to 1 to keep the filter, or remove the filter to read in parallel.","messagePattern":"HugeGraph source 'filter' cannot be combined with parallelism > 1 \\(runtime parallelism is (.+?)\\): parallel reads use shard key-range scans that do not support server-side property filtering\\. Either set parallelism to 1 to keep the filter, or remove the filter to read in parallel\\.","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":143,"sourceCode":"            }\n            LOG.info(\n                    \"HugeGraph source: read-all-labels, created {} label-list split(s) for {} \"\n                            + \"labels {}\",\n                    allSplits.size(),\n                    sourceConfig.getLabelType(),\n                    sourceConfig.getLabels());\n            return;\n        }\n        int parallelism = context.currentParallelism();\n\n        // Runtime guard: the factory-level checkFilterParallelism() reads the per-source\n        // 'parallelism' option, which does not see env { parallelism = N }. This runtime check\n        // catches the combination at the last safe point — before any shard splits are created\n        // — so filter + parallelism > 1 is guaranteed to fail fast.\n        Map<String, Object> filter = sourceConfig.getFilter();\n        boolean hasFilter = filter != null && !filter.isEmpty();\n        if (parallelism > 1 && hasFilter) {\n            throw new HugeGraphConnectorException(\n                    HugeGraphConnectorErrorCode.ILLEGAL_CONFIG_ARGUMENT,\n                    String.format(\n                            \"HugeGraph source 'filter' cannot be combined with parallelism > 1 \"\n                                    + \"(runtime parallelism is %d): parallel reads use shard \"\n                                    + \"key-range scans that do not support server-side property \"\n                                    + \"filtering. Either set parallelism to 1 to keep the filter, \"\n                                    + \"or remove the filter to read in parallel.\",\n                            parallelism));\n        }\n\n        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        }","sourceCodeStart":125,"sourceCodeEnd":161,"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#L125-L161","documentation":"The HugeGraph source reads in parallel using shard key-range scans, which do not support server-side property filtering. If a non-empty 'filter' option is combined with runtime parallelism > 1, the split enumerator's discover() fails fast with ILLEGAL_CONFIG_ARGUMENT rather than silently ignoring the filter.","triggerScenarios":"HugeGraph source configured with both filter = {...} and parallelism > 1 (or the job's env parallelism being > 1 at runtime).","commonSituations":"Adding a filter to an existing parallel job; assuming the source's 'parallelism' option accounts for env { parallelism = N }; scaling up parallelism without reviewing the filter.","solutions":["Set parallelism = 1 for the source to keep the filter.","Remove the filter option to keep parallel reading.","Move the filtering downstream (e.g. a SQL/transform filter after the source) if parallelism must stay > 1."],"exampleFix":"// before\nHugeGraph {\n  parallelism = 4\n  filter = { age = 20 }\n}\n// after\nHugeGraph {\n  parallelism = 1\n  filter = { age = 20 }\n}","handlingStrategy":"validation","validationCode":"boolean hasFilter = config.filter != null && !config.filter.isEmpty();\nif (hasFilter && runtimeParallelism > 1) {\n    throw new IllegalArgumentException(\"filter requires parallelism = 1\");\n}","typeGuard":null,"tryCatchPattern":"try { job.submit(); } catch (HugeGraphConnectorException e) {\n    if (e.getErrorCode() == HugeGraphConnectorErrorCode.ILLEGAL_CONFIG_ARGUMENT\n            && e.getMessage().contains(\"cannot be combined with parallelism\")) {\n        // set parallelism = 1, drop the filter, or filter downstream\n    }\n}","preventionTips":["Treat filter and parallelism>1 as mutually exclusive options","If env parallelism is >1, avoid source-side filters or filter downstream","Document the constraint in job templates to catch it in review"],"tags":["hugegraph","config","parallelism","filter"],"backgroundTag":"conflicting-config-options","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"}