apache/seatunnel · error · HugeGraphConnectorException

INVALID_GRAPH_SCHEMA

INVALID_GRAPH_SCHEMA

Error message

Unsupported cardinality: '%s'

What it means

DataTypeUtil.convert maps HugeGraph property cardinality values to SeaTunnel list/array types. When the schema declares a cardinality outside the supported set (single, list, set), the default branch throws INVALID_GRAPH_SCHEMA with this message.

Source

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

        DataType dataType = propertyKey.dataType();
        Cardinality cardinality = propertyKey.cardinality();
        switch (cardinality) {
            case SINGLE:
                return parseSingleValue(
                        key, value, dataType, dateFormat, timeZone, extraDateFormats);
            case SET:
            case LIST:
                return parseMultiValues(
                        key,
                        value,
                        dataType,
                        cardinality,
                        dateFormat,
                        timeZone,
                        extraDateFormats,
                        listFormat);
            default:
                throw new HugeGraphConnectorException(
                        HugeGraphConnectorErrorCode.INVALID_GRAPH_SCHEMA,
                        String.format("Unsupported cardinality: '%s'", cardinality));
        }
    }

    /**
     * collection format: "obj1,obj2,...,obj_n" or "[obj1,obj2,...,obj_n]" ..etc TODO: After parsing
     * to json, the order of the collection changed in some cases (such as list<date>)
     */
    private static Object parseMultiValues(
            String key,
            Object values,
            DataType dataType,
            Cardinality cardinality,
            String dateFormat,
            String timeZone,
            List<String> extraDateFormats,
            ListFormat listFormat) {

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Check the property key's cardinality with HugeGraph's schema API and set it to one of single, list, or set.
  2. If the cardinality is valid but unmapped, upgrade the SeaTunnel hugegraph connector or open an issue to add support.
  3. Recreate the property key with a supported cardinality (HugeGraph does not allow changing cardinality in place).

Example fix

// before
schema.propertyKey("tags").cardinality(Cardinality.OTHER).valueText().create();
// after
schema.propertyKey("tags").cardinality(Cardinality.LIST).valueText().create();
Defensive patterns

Strategy: validation

Validate before calling

// before ingest: verify cardinality of each property key
Set<String> allowed = Set.of("SINGLE", "LIST", "SET");
for (PropertyKey pk : schema().getPropertyKeys()) {
    if (!allowed.contains(pk.cardinality().name())) {
        throw new IllegalArgumentException("Unsupported cardinality on " + pk.name());
    }
}

Try / catch

try {
    SeaTunnelRow row = converter.convert(hugeGraphVertex);
} catch (HugeGraphConnectorException e) {
    if (e.getCode() == INVALID_GRAPH_SCHEMA && e.getMessage().contains("Unsupported cardinality")) {
        LOG.error("Fix property key cardinality in HugeGraph schema: {}", e.getMessage());
    }
    throw e;
}

Prevention

When it happens

Trigger: A HugeGraph property key schema uses an unexpected/unknown cardinality value, and the connector calls DataTypeUtil.convert (via convert) to map the schema type during read setup.

Common situations: Schema created directly against the HugeGraph API with a cardinality the connector does not recognize, or a schema modified/added in a newer HugeGraph version not yet mapped by the connector.

Related errors

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