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

ParquetReadStrategy resolves Parquet groups to SeaTunnel types using the native Group API. When a field's Parquet logical/original type is not one the reader can convert (at resolveGroupType it only handles LIST and MAP group annotations), it throws COMMON-17 'unsupported convert type ... to SeaTunnel data type'. It means the reader encountered a Parquet type in the file schema it has no mapping for.

Source

Thrown at seatunnel-connectors-v2/connector-file/connector-file-base/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/source/reader/ParquetReadStrategy.java:283

        if (logicalTypeAnnotation == null) {
            SeaTunnelRowType rowType = (SeaTunnelRowType) fieldType;
            Group childGroup = group.getGroup(fieldIndex, 0);
            Object[] objects = new Object[rowType.getTotalFields()];
            for (int i = 0; i < rowType.getTotalFields(); i++) {
                objects[i] =
                        resolveGroupObject(
                                childGroup, groupType.getType(i), i, rowType.getFieldType(i));
            }
            return new SeaTunnelRow(objects);
        }
        OriginalType originalType = logicalTypeAnnotation.toOriginalType();
        if (originalType == OriginalType.LIST) {
            return readList(group, groupType, fieldIndex, fieldType);
        }
        if (originalType == OriginalType.MAP) {
            return readMap(group, groupType, fieldIndex, fieldType);
        }
        throw CommonError.convertToSeaTunnelTypeError(
                PARQUET, parquetType.toString(), parquetType.getName());
    }

    /**
     * Reads a LIST field from a Parquet Group using the native Group API. Handles both the standard
     * 3-level LIST encoding (group → repeated list → element) and the legacy 2-level encoding
     * (group → repeated element directly).
     */
    private Object readList(
            Group group,
            GroupType parentGroupType,
            int listFieldIndex,
            SeaTunnelDataType<?> fieldType) {
        // Check if the LIST field is present
        if (group.getFieldRepetitionCount(listFieldIndex) == 0) {
            return new Object[0];
        }

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Inspect the Parquet schema (parquet-tools / pyspark printSchema) and identify the unsupported field; re-write the file casting it to a supported type (primitive, LIST, MAP).
  2. Exclude or project out the unsupported nested column in the upstream writer so the SeaTunnel file source only sees supported types.
  3. Upgrade SeaTunnel to a newer version where more Parquet group types are supported.
  4. Flatten the nested struct into top-level primitive columns before writing the Parquet file.

Example fix

// before (upstream Spark write with a nested struct column)
df.write.parquet("s3://bucket/data")  // df contains column 'addr' of struct type
// after
df.drop("addr").write.parquet("s3://bucket/data")
// or flatten: df.select(col("addr.city").as("city"), col("addr.zip").as("zip"))
Defensive patterns

Strategy: validation

Validate before calling

// Inspect the Parquet schema before reading
import org.apache.parquet.hadoop.ParquetFileReader;
import org.apache.parquet.schema.MessageType;
try (ParquetFileReader r = ParquetFileReader.open(new org.apache.hadoop.fs.Path(path))) {
    MessageType schema = r.getFooter().getSchema();
    schema.getFields().forEach(f -> {
        if (f.isPrimitive() == false
                && f.asGroupType().getLogicalTypeAnnotation() != null
                && !f.asGroupType().getLogicalTypeAnnotation()
                       .toString().matches(".*(LIST|MAP).*")) {
            throw new IllegalStateException("Unsupported nested group: " + f.getName());
        }
    });
}

Try / catch

try {
    strategy.resolveGroupObject(group, groupType, fieldIndex, fieldType);
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().contains("unsupported convert type")) {
        LOGGER.error("Parquet field {} has a type the reader cannot map; rewrite or drop it", field, e);
        return null; // or fail fast after logging schema details
    }
    throw e;
}

Prevention

When it happens

Trigger: Thrown in ParquetReadStrategy.resolveGroupType (line 283) when a Parquet GroupType field has a LogicalTypeAnnotation that is neither LIST nor MAP (e.g. an unannotated nested group or an unsupported annotation), called from resolveGroupObject during schema resolution or row conversion.

Common situations: 1) Files written with nested structures (structs/groups) that the reader doesn't support. 2) Parquet files written by tools using uncommon logical type annotations (e.g. variant, custom annotations). 3) Schema drift: a column type changed in the upstream writer to a nested type. 4) Reading files produced by an older/newer writer with types outside the reader's supported set.

Related errors

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