apache/seatunnel · error · HugeGraphConnectorException

HugeGraphConnectorErrorCode.ILLEGAL_CONFIG_ARGUMENT

HugeGraphConnectorErrorCode.ILLEGAL_CONFIG_ARGUMENT

Error message

Mapping[EDGE/%s]: 'sortKeys' must be specified when frequency is MULTIPLE.

What it means

SchemaManager.createEdgeLabelIfMissing creates an EDGE label; HugeGraph requires sortKeys for edges whose frequency is MULTIPLE. When frequency=MULTIPLE but the mapping's sortKeys resolve to null/empty, the connector throws ILLEGAL_CONFIG_ARGUMENT because such an edge label cannot be created.

Solutions

Add sort_keys to the EDGE mapping, naming source fields that map to existing PropertyKeys (e.g. sort_keys = ["timestamp"]).
Change frequency to SINGLE if multiple edges between the same vertices are not needed.
Ensure the sort key source fields exist in the input row so mapToTargetNames yields non-empty results.
If the edge label already exists server-side, use a schema save mode that reuses it instead of creating.

Example fix

// before
mapping = {
  type = EDGE
  label = "likes"
  frequency = MULTIPLE
}
// after
mapping = {
  type = EDGE
  label = "likes"
  frequency = MULTIPLE
  sort_keys = ["created_at"]
}

Defensive patterns

Strategy: validation

Validate before calling

// Validate edge mapping before submission
if ("MULTIPLE".equalsIgnoreCase(edgeMapping.frequency)) {
  if (edgeMapping.sortKeys == null || edgeMapping.sortKeys.isEmpty()) {
    throw new IllegalArgumentException("sort_keys must be set when frequency is MULTIPLE");
  }
}

Try / catch

try {
  submitJob(config);
} catch (HugeGraphConnectorException e) {
  if (e.getMessage() != null && e.getMessage().contains("sortKeys")) {
    log.error("Edge mapping config error: {}", e.getMessage());
  }
  throw e;
}

Prevention

Always pair frequency=MULTIPLE with explicit sort_keys in edge mappings
Confirm the sort key source fields exist in the input row
Use SINGLE frequency when parallel duplicate edges are not needed
Validate mapping configs in CI with a dry-run/local job

When it happens

Trigger: A mapping config for an EDGE label sets frequency = MULTIPLE but omits sort_keys (or sort_keys maps to an empty list after field-mapping translation) while ensureSchema attempts to create the edge label.

Common situations: User copies an edge mapping template and forgets sort_keys; frequency is set to MULTIPLE to allow parallel edges but no sort keys were defined; sort_keys reference fields dropped upstream.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-hugegraph/src/main/java/org/apache/seatunnel/connectors/seatunnel/hugegraph/utils/SchemaManager.java:316

    private void createEdgeLabelIfMissing(MappingConfig mapping, Set<String> propertyNames) {
        if (client.getEdgeLabelOrNull(mapping.getLabel()) != null) {
            LOG.debug("EdgeLabel '{}' already exists, skipping creation.", mapping.getLabel());
            return;
        }

        E.checkNotNull(mapping.getSourceConfig(), "sourceConfig", "edge mapping");
        E.checkNotNull(mapping.getTargetConfig(), "targetConfig", "edge mapping");

        Frequency frequency =
                mapping.getFrequency() != null ? mapping.getFrequency() : Frequency.SINGLE;
        // Sort keys must reference target property names (after fieldMapping)
        List<String> sortKeys =
                frequency == Frequency.MULTIPLE
                        ? mapToTargetNames(mapping.getSortKeys(), mapping.getFieldMapping())
                        : null;

        if (frequency == Frequency.MULTIPLE && (sortKeys == null || sortKeys.isEmpty())) {
            throw new HugeGraphConnectorException(
                    HugeGraphConnectorErrorCode.ILLEGAL_CONFIG_ARGUMENT,
                    String.format(
                            "Mapping[EDGE/%s]: 'sortKeys' must be specified when frequency is MULTIPLE.",
                            mapping.getLabel()));
        }

        List<String> nullableKeys = computeNullableKeys(mapping, propertyNames);

        LOG.info(
                "Mapping[EDGE/{}]: Auto-creating EdgeLabel ({}→{}) with frequency={}, properties={}",
                mapping.getLabel(),
                mapping.getSourceConfig().getLabel(),
                mapping.getTargetConfig().getLabel(),
                frequency,
                propertyNames);
        client.createEdgeLabelIfNotExist(
                mapping.getLabel(),
                mapping.getSourceConfig().getLabel(),

View on GitHub (pinned to cf67b549a7)