apache/seatunnel · error · HugeGraphConnectorException

ILLEGAL_CONFIG_ARGUMENT

ILLEGAL_CONFIG_ARGUMENT

Error message

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

What it means

VertexMapper.coerceCustomizeId converts unfold element values into vertex IDs and supports only CUSTOMIZE_STRING, CUSTOMIZE_NUMBER and CUSTOMIZE_UUID IdStrategies. Any other strategy reaches the default branch and throws ILLEGAL_CONFIG_ARGUMENT.

Solutions

Set the vertex id_strategy to CUSTOMIZE_STRING, CUSTOMIZE_NUMBER, or CUSTOMIZE_UUID when using unfold
Drop the unfold option if ids should be generated by HugeGraph
Ensure the id column referenced by unfold contains concrete id values

Example fix

// before
vertex = { id_strategy = "PRIMARY_KEY" }
// 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 CUSTOMIZE_STRING/NUMBER/UUID");
}

Try / catch

try { vertexMapper.mapAll(rows); } catch (HugeGraphConnectorException e) { if (e.getMessage().contains("unfold requires")) { /* set a CUSTOMIZE_* id_strategy */ } }

Prevention

Enable unfold only for vertices with customize id strategies
Avoid mixing unfold with AUTOMATIC/PRIMARY_KEY id generation
Validate id_strategy early in config review

When it happens

Trigger: Calling coerceCustomizeId from mapAll with unfold values while the vertex id_strategy is not one of the three customize strategies (e.g. AUTOMATIC or PRIMARY_KEY).

Common situations: Using unfold to write vertices whose ids are server-generated; switching id_strategy to PRIMARY_KEY after adding unfold support; template configs copied between graphs.

Related errors

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

Appendix: source

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

            Vertex vertex = new Vertex(mappingConfig.getLabel());
            vertex.id(coerceCustomizeId(strategy, elem));
            // The id field is the unfolded source, not a property — skip it.
            applyProperties(vertex, row, idField);
            result.add(vertex);
        }
        return result;
    }

    private static Object coerceCustomizeId(IdStrategy strategy, Object elem) {
        switch (strategy) {
            case CUSTOMIZE_STRING:
                return checkVertexIdLength(String.valueOf(elem));
            case CUSTOMIZE_NUMBER:
                return 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 id strategy, but got "
                                + strategy);
        }
    }

    private void applyProperties(Vertex vertex, SeaTunnelRow row, String skipField) {
        Map<String, String> fm = mappingConfig.getFieldMapping();
        for (String sourceField : propertySourceFields) {
            if (sourceField.equals(skipField)) {
                continue;
            }
            Integer index = fieldsIndex.get(sourceField);
            if (index == null) {
                continue;
            }

            String propName = fm.getOrDefault(sourceField, sourceField);

View on GitHub (pinned to cf67b549a7)