apache/iceberg · error · UnsupportedOperationException

Field %d has unsupported field type: %s

Error message

Field %d has unsupported field type: %s

What it means

SortKeySerializer.serialize throws UnsupportedOperationException when a sort-order field's transformed type is STRUCT, MAP, LIST, or any otherwise unrecognized type ID. Iceberg's sort-key shuffle feature flattens sort keys into a struct of primitive fields only; nested types cannot be serialized as flattened sort-key fields, so the serializer refuses them eagerly.

Source

Thrown at flink/v1.20/flink/src/main/java/org/apache/iceberg/flink/sink/shuffle/SortKeySerializer.java:197

        case FIXED:
        case BINARY:
          byte[] bytes = record.get(i, ByteBuffer.class).array();
          target.writeInt(bytes.length);
          target.write(bytes);
          break;
        case DECIMAL:
          BigDecimal decimal = record.get(i, BigDecimal.class);
          byte[] decimalBytes = decimal.unscaledValue().toByteArray();
          target.writeInt(decimalBytes.length);
          target.write(decimalBytes);
          target.writeInt(decimal.scale());
          break;
        case STRUCT:
        case MAP:
        case LIST:
        default:
          // SortKey transformation is a flattened struct without list and map
          throw new UnsupportedOperationException(
              String.format(
                  Locale.ROOT, "Field %d has unsupported field type: %s", fieldId, typeId));
      }
    }
  }

  @Override
  public SortKey deserialize(DataInputView source) throws IOException {
    // copying is a little faster than constructing a new SortKey object
    SortKey deserialized = lazySortKey().copy();
    deserialize(deserialized, source);
    return deserialized;
  }

  @Override
  public SortKey deserialize(SortKey reuse, DataInputView source) throws IOException {
    Preconditions.checkArgument(
        reuse.size() == size,

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Change the table's sort order so all sort fields reference primitive-typed columns (string, int, long, etc.)
  2. Remove the nested-typed column from the sort order, or sort by a primitive top-level column derived from it (e.g. a flattened key column)
  3. Use a transform that yields a primitive result type for the sort field, and verify with CheckCompatibility before building the writer

Example fix

// before: sort order on a list column
Table table = ...; table.updateSort().addSortField(icebergTypeListColumnId, SortDirection.ASC).commit();
// after: sort by a primitive column instead
table.updateSort().addSortField(primitiveColumnId, SortDirection.ASC).commit();
Defensive patterns

Strategy: validation

Validate before calling

import org.apache.iceberg.types.CheckCompatibility;
import org.apache.iceberg.SortOrder;
// fail fast before wiring the sort-key shuffle writer
List<Types.NestedField> fields = sortOrder.fields().stream()
    .map(sf -> schema.findField(sf.sourceId()))
    .collect(Collectors.toList());
CheckCompatibility.checkFieldTypeCompatibility? // or simply:
for (SortField sf : sortOrder.fields()) {
  org.apache.iceberg.types.Type t = schema.findField(sf.sourceId()).type();
  Preconditions.checkArgument(t.isPrimitiveType(),
      "Sort field %s must be primitive, got %s", sf.sourceId(), t);
}

Prevention

When it happens

Trigger: Calling SortKeySerializer.serialize (directly or via copy/Flink's serializer machinery such as testSerializationSize) on a SortKey whose SortOrder references a source column of type struct, map, or list (or a transform whose result type is nested).

Common situations: Declaring an ORDER BY / sort order on a nested column (e.g. a list or map column) in the Iceberg table's sort order used by the Flink sorted-shuffle writer; passing a table with a struct-typed sort column to the sort-key shuffle operator.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/53db4e282982c9cd. Report an issue: GitHub.