apache/seatunnel · error · org.apache.seatunnel.common.exception.SeaTunnelRuntimeException

COMMON-17

COMMON-17

Error message

'<identifier>' unsupported convert type '<dataType>' of '<field>' to SeaTunnel data type.

What it means

SchemaUtil.convertSeaTunnelType maps Avro (Hudi) schemas to SeaTunnel types. When a UNION schema has more than two branches, or the two-branch union's non-null branch cannot be resolved as expected, it throws COMMON-17 convertToSeaTunnelTypeError with the Hudi identifier, the schema type name, and the field. Only single-type and simple nullable unions (type|null) are supported.

Source

Thrown at seatunnel-connectors-v2/connector-hudi/src/main/java/org/apache/seatunnel/connectors/seatunnel/hudi/util/SchemaUtil.java:101

                return BasicType.LONG_TYPE;
            case FLOAT:
                return BasicType.FLOAT_TYPE;
            case DOUBLE:
                return BasicType.DOUBLE_TYPE;
            case BOOLEAN:
                return BasicType.BOOLEAN_TYPE;
            case UNION:
                final Schema actualSchema;
                if (schema.getTypes().size() == 2
                        && schema.getTypes().get(0).getType() == Schema.Type.NULL) {
                    actualSchema = schema.getTypes().get(1);
                } else if (schema.getTypes().size() == 2
                        && schema.getTypes().get(1).getType() == Schema.Type.NULL) {
                    actualSchema = schema.getTypes().get(0);
                } else if (schema.getTypes().size() == 1) {
                    actualSchema = schema.getTypes().get(0);
                } else {
                    throw CommonError.convertToSeaTunnelTypeError(
                            "Hudi", schema.getType().name(), field);
                }
                return convertSeaTunnelType(field, actualSchema);
            default:
                throw CommonError.convertToSeaTunnelTypeError(
                        "Hudi", schema.getType().name(), field);
        }
    }

    private static MapType convertMapType(String field, Schema schema) {
        return new MapType(
                convertSeaTunnelType(field, schema.getElementType()),
                convertSeaTunnelType(field, schema.getValueType()));
    }

    private static SeaTunnelRowType convertStructType(Schema schema) {
        List<Schema.Field> fields = schema.getFields();
        List<String> fieldNames = new ArrayList<>(fields.size());

View on GitHub (pinned to cf67b549a7)

Solutions

1. Normalize the Hudi/Avro schema so unions are at most 'type|null' (rewrite table schema or use a schema that collapses branches)
2. Change the field type on write so it is a single concrete type
3. Pre-process the Avro schema before conversion by patching SchemaUtil usage (custom build)
4. Report/track support for multi-branch Avro union conversion in SeaTunnel

Example fix

// before
"field": ["int", "long", "null"]
// after
"field": ["long", "null"]

// Inspect Avro union branches of the Hudi schema before conversion
for (Schema.Field f : avroSchema.getFields()) {
    if (f.schema().getType() == Schema.Type.UNION
            && f.schema().getTypes().size() > 2) {
        throw new IllegalArgumentException(
            "Field " + f.name() + " has unsupported multi-branch union");
    }
}

boolean isSimpleNullableUnion(Schema s) {
    return s.getType() == Schema.Type.UNION
        && (s.getTypes().size() == 1
            || (s.getTypes().size() == 2
                && s.getTypes().get(1).getType() == Schema.Type.NULL));
}

When it happens

Trigger: A Hudi (Avro) record field has a union schema with 3+ member types, or a 2-member union whose second type is not NULL, so no 'actualSchema' can be picked.

Common situations: Hudi tables written by engines that produce multi-branch unions (e.g. int|long|null, enum unions); schema evolution merging several historical types into one field.

Related errors

• Unsupported to derive Schema for type: ${dataType}
• Avro format doesn't support non-string as key type of map. T
• Unsupported type: ${dataType}
• The Avro schema is not a nullable type: ${schema}
• Fail to serialize at field: ${fieldName}.

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