apache/seatunnel · error · HugeGraphConnectorException

ILLEGAL_CONFIG_ARGUMENT

ILLEGAL_CONFIG_ARGUMENT

Error message

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.

What it means

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.

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.

Example fix

// before
HugeGraph {
  parallelism = 4
  filter = { age = 20 }
}
// after
HugeGraph {
  parallelism = 1
  filter = { age = 20 }
}

Defensive patterns

Strategy: validation

Validate before calling

boolean hasFilter = config.filter != null && !config.filter.isEmpty();
if (hasFilter && runtimeParallelism > 1) {
    throw new IllegalArgumentException("filter requires parallelism = 1");
}

Try / catch

try { job.submit(); } catch (HugeGraphConnectorException e) {
    if (e.getErrorCode() == HugeGraphConnectorErrorCode.ILLEGAL_CONFIG_ARGUMENT
            && e.getMessage().contains("cannot be combined with parallelism")) {
        // set parallelism = 1, drop the filter, or filter downstream
    }
}

Prevention

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

When it happens

Trigger: HugeGraph source configured with both filter = {...} and parallelism > 1 (or the job's env parallelism being > 1 at runtime).

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

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/fe037fc778b051b7. 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:143

            }
            LOG.info(
                    "HugeGraph source: read-all-labels, created {} label-list split(s) for {} "
                            + "labels {}",
                    allSplits.size(),
                    sourceConfig.getLabelType(),
                    sourceConfig.getLabels());
            return;
        }
        int parallelism = context.currentParallelism();

        // Runtime guard: the factory-level checkFilterParallelism() reads the per-source
        // 'parallelism' option, which does not see env { parallelism = N }. This runtime check
        // catches the combination at the last safe point — before any shard splits are created
        // — so filter + parallelism > 1 is guaranteed to fail fast.
        Map<String, Object> filter = sourceConfig.getFilter();
        boolean hasFilter = filter != null && !filter.isEmpty();
        if (parallelism > 1 && hasFilter) {
            throw new HugeGraphConnectorException(
                    HugeGraphConnectorErrorCode.ILLEGAL_CONFIG_ARGUMENT,
                    String.format(
                            "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.",
                            parallelism));
        }

        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;
        }

View on GitHub (pinned to cf67b549a7)