{"record":{"id":"102d17e496ddd291","repo":"apache/seatunnel","slug":"hugegraphconnectorerrorcode-illegal-config-argumen-102d17","errorCode":"HugeGraphConnectorErrorCode.ILLEGAL_CONFIG_ARGUMENT","errorMessage":"Mapping[EDGE/%s]: 'sortKeys' must be specified when frequency is MULTIPLE.","messagePattern":"Mapping\\[EDGE/(.+?)\\]: 'sortKeys' must be specified when frequency is MULTIPLE\\.","errorType":"error_code","errorClass":"HugeGraphConnectorException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-hugegraph/src/main/java/org/apache/seatunnel/connectors/seatunnel/hugegraph/utils/SchemaManager.java","lineNumber":316,"sourceCode":"    private void createEdgeLabelIfMissing(MappingConfig mapping, Set<String> propertyNames) {\n        if (client.getEdgeLabelOrNull(mapping.getLabel()) != null) {\n            LOG.debug(\"EdgeLabel '{}' already exists, skipping creation.\", mapping.getLabel());\n            return;\n        }\n\n        E.checkNotNull(mapping.getSourceConfig(), \"sourceConfig\", \"edge mapping\");\n        E.checkNotNull(mapping.getTargetConfig(), \"targetConfig\", \"edge mapping\");\n\n        Frequency frequency =\n                mapping.getFrequency() != null ? mapping.getFrequency() : Frequency.SINGLE;\n        // Sort keys must reference target property names (after fieldMapping)\n        List<String> sortKeys =\n                frequency == Frequency.MULTIPLE\n                        ? mapToTargetNames(mapping.getSortKeys(), mapping.getFieldMapping())\n                        : null;\n\n        if (frequency == Frequency.MULTIPLE && (sortKeys == null || sortKeys.isEmpty())) {\n            throw new HugeGraphConnectorException(\n                    HugeGraphConnectorErrorCode.ILLEGAL_CONFIG_ARGUMENT,\n                    String.format(\n                            \"Mapping[EDGE/%s]: 'sortKeys' must be specified when frequency is MULTIPLE.\",\n                            mapping.getLabel()));\n        }\n\n        List<String> nullableKeys = computeNullableKeys(mapping, propertyNames);\n\n        LOG.info(\n                \"Mapping[EDGE/{}]: Auto-creating EdgeLabel ({}→{}) with frequency={}, properties={}\",\n                mapping.getLabel(),\n                mapping.getSourceConfig().getLabel(),\n                mapping.getTargetConfig().getLabel(),\n                frequency,\n                propertyNames);\n        client.createEdgeLabelIfNotExist(\n                mapping.getLabel(),\n                mapping.getSourceConfig().getLabel(),","sourceCodeStart":298,"sourceCodeEnd":334,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-hugegraph/src/main/java/org/apache/seatunnel/connectors/seatunnel/hugegraph/utils/SchemaManager.java#L298-L334","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nmapping = {\n  type = EDGE\n  label = \"likes\"\n  frequency = MULTIPLE\n}\n// after\nmapping = {\n  type = EDGE\n  label = \"likes\"\n  frequency = MULTIPLE\n  sort_keys = [\"created_at\"]\n}","handlingStrategy":"validation","validationCode":"// Validate edge mapping before submission\nif (\"MULTIPLE\".equalsIgnoreCase(edgeMapping.frequency)) {\n  if (edgeMapping.sortKeys == null || edgeMapping.sortKeys.isEmpty()) {\n    throw new IllegalArgumentException(\"sort_keys must be set when frequency is MULTIPLE\");\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  submitJob(config);\n} catch (HugeGraphConnectorException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"sortKeys\")) {\n    log.error(\"Edge mapping config error: {}\", e.getMessage());\n  }\n  throw e;\n}","preventionTips":["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"],"tags":["hugegraph","edge","sort-keys","config-validation"],"backgroundTag":"missing-required-config-field","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"}