apache/seatunnel · error · HugeGraphConnectorException

HugeGraphConnectorErrorCode.INVALID_GRAPH_SCHEMA

HugeGraphConnectorErrorCode.INVALID_GRAPH_SCHEMA

Error message

Property '%s': type BLOB with cardinality %s is not supported for reads.

What it means

HugeGraphTypeConverter.toSeaTunnelType converts HugeGraph property types (with cardinality) to SeaTunnel types. A BLOB property with a non-SINGLE cardinality (e.g. LIST/SET of blobs) would map to byte[][], which SeaTunnel operators do not uniformly handle, so the connector rejects the schema up front with a clear INVALID_GRAPH_SCHEMA error instead of failing later with a ClassCastException.

Source

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

public final class HugeGraphTypeConverter {

    private HugeGraphTypeConverter() {}

    /**
     * Maps a HugeGraph property type + cardinality to a SeaTunnel type. A {@code LIST}/{@code SET}
     * cardinality becomes {@code array<element>}; {@code SINGLE} (or null) stays scalar. The {@code
     * propertyName} is used only to make any error message point at the offending column.
     */
    public static SeaTunnelDataType<?> toSeaTunnelType(
            DataType dataType, Cardinality cardinality, String propertyName) {
        SeaTunnelDataType<?> scalar = toSeaTunnelScalarType(dataType, propertyName);
        if (cardinality == null || cardinality == Cardinality.SINGLE) {
            return scalar;
        }
        // BLOB elements would produce byte[][], which downstream SeaTunnel operators do not
        // uniformly handle — reject with a clear message rather than a mysterious CCE later.
        if (dataType == DataType.BLOB) {
            throw new HugeGraphConnectorException(
                    HugeGraphConnectorErrorCode.INVALID_GRAPH_SCHEMA,
                    String.format(
                            "Property '%s': type BLOB with cardinality %s is not supported for reads.",
                            propertyName, cardinality));
        }
        return ArrayType.of(scalar);
    }

    public static SeaTunnelDataType<?> toSeaTunnelScalarType(
            DataType dataType, String propertyName) {
        switch (dataType) {
            case TEXT:
                return BasicType.STRING_TYPE;
            case BYTE:
                return BasicType.BYTE_TYPE;
            case INT:
                return BasicType.INT_TYPE;
            case LONG:

View on GitHub (pinned to cf67b549a7)

Solutions

Change the property cardinality to SINGLE in HugeGraph if the data allows it (BLOB+SINGLE maps to byte[] and is supported).
Exclude the BLOB multi-cardinality property from the read (adjust the field/property selection for the source).
Pre-transform the data in HugeGraph to a supported representation (e.g. store base64 TEXT in a LIST).
If you control the model, split the blob list into separate SINGLE properties or a different label.

Example fix

// before (HugeGraph schema)
schema.propertyKey("attachments").asBlob().cardinalityList().create();
// after
schema.propertyKey("attachment").asBlob().cardinalitySingle().create();
// or store as text list:
schema.propertyKey("attachments").asText().cardinalityList().create();

Defensive patterns

Strategy: validation

Validate before calling

// Before reading, inspect the HugeGraph schema for multi-cardinality BLOB properties
for (PropertyKey pk : schema.getPropertyKeys()) {
  if (pk.dataType() == DataType.BLOB && pk.cardinality() != Cardinality.SINGLE) {
    throw new IllegalStateException(
      "Property " + pk.name() + " is multi-cardinality BLOB; exclude it from the read");
  }
}

Try / catch

try {
  readLabel(label);
} catch (HugeGraphConnectorException e) {
  if (e.getMessage() != null && e.getMessage().contains("BLOB with cardinality")) {
    // adjust field selection to skip the offending property
  }
  throw e;
}

Prevention

Model multi-valued data as TEXT instead of LIST<BLOB> when downstream readers exist
Check HugeGraph schema before designing SeaTunnel field lists
Keep BLOB properties SINGLE cardinality if byte[] is acceptable
Document graph schema constraints for sink/source authors

When it happens

Trigger: A source read against a vertex/edge label whose schema contains a PropertyKey of DataType BLOB with cardinality LIST or SET; the error fires while building the SeaTunnel catalog table from the HugeGraph schema.

Common situations: HugeGraph graph was modeled with list-of-bytes properties (e.g. embedded binary attachments, serialized blobs stored as LIST<BLOB>) and SeaTunnel tries to read that label.

Related errors

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