apache/seatunnel · error · HugeGraphConnectorException

ILLEGAL_CONFIG_ARGUMENT

ILLEGAL_CONFIG_ARGUMENT

Error message

unfold requires a CUSTOMIZE_STRING/NUMBER/UUID endpoint id strategy, but got %s

What it means

EdgeMapper.coerceCustomizeId converts unfold values into vertex IDs, but only CUSTOMIZE_STRING, CUSTOMIZE_NUMBER and CUSTOMIZE_UUID IdStrategies are supported for this path. Any other strategy reaches the default branch and throws ILLEGAL_CONFIG_ARGUMENT.

Solutions

Set the endpoint vertex id_strategy to CUSTOMIZE_STRING, CUSTOMIZE_NUMBER, or CUSTOMIZE_UUID
Remove the unfold configuration if IDs should be server-generated
Ensure unfold values are plain id values, not primary-key field maps

Example fix

// before
vertex = { id_strategy = "AUTOMATIC" }
// after
vertex = { id_strategy = "CUSTOMIZE_STRING" }

Defensive patterns

Strategy: validation

Validate before calling

if (unfoldEnabled && strategy != CUSTOMIZE_STRING && strategy != CUSTOMIZE_NUMBER && strategy != CUSTOMIZE_UUID) {
  throw new IllegalArgumentException("unfold requires a CUSTOMIZE_* id strategy");
}

Try / catch

try { edgeMapper.map(row); } catch (HugeGraphConnectorException e) { if (e.getMessage().contains("unfold requires")) { /* switch id_strategy to a CUSTOMIZE_* value */ } }

Prevention

Only enable unfold with CUSTOMIZE_STRING/NUMBER/UUID strategies
Review vertex id_strategy whenever adding unfold config
Keep unfold and server-generated ids mutually exclusive

When it happens

Trigger: Calling coerceCustomizeId (via buildVertexIdList) with unfold data while the endpoint vertex's id_strategy is PRIMARY_KEY, AUTOMATIC, or another non-customize strategy.

Common situations: Configuring unfold for edge endpoints while vertices use automatic/primary-key ID generation; changing a vertex id_strategy without updating unfold usage.

Related errors

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-hugegraph/src/main/java/org/apache/seatunnel/connectors/seatunnel/hugegraph/mapper/EdgeMapper.java:239

        for (Object elem : elements) {
            if (isConsideredNull(elem)) {
                continue;
            }
            ids.add(coerceCustomizeId(strategy, elem));
        }
        return ids;
    }

    private static Object coerceCustomizeId(IdStrategy strategy, Object elem) {
        switch (strategy) {
            case CUSTOMIZE_STRING:
                return VertexMapper.checkVertexIdLength(String.valueOf(elem));
            case CUSTOMIZE_NUMBER:
                return VertexMapper.coerceNumberId(elem);
            case CUSTOMIZE_UUID:
                return elem instanceof UUID ? elem : UUID.fromString(String.valueOf(elem));
            default:
                throw new HugeGraphConnectorException(
                        HugeGraphConnectorErrorCode.ILLEGAL_CONFIG_ARGUMENT,
                        "unfold requires a CUSTOMIZE_STRING/NUMBER/UUID endpoint id strategy, but got "
                                + strategy);
        }
    }

    private Edge buildEdge(SeaTunnelRow row, Object sourceId, Object targetId) {
        Edge edge = new Edge(mappingConfig.getLabel());
        edge.sourceId(sourceId);
        edge.targetId(targetId);
        edge.sourceLabel(mappingConfig.getSourceConfig().getLabel());
        edge.targetLabel(mappingConfig.getTargetConfig().getLabel());

        Map<String, String> fm = mappingConfig.getFieldMapping();
        for (String sourceField : propertySourceFields) {
            Integer index = fieldsIndex.get(sourceField);
            if (index == null) {
                continue;

View on GitHub (pinned to cf67b549a7)