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 SortKey field has a type (STRUCT, MAP, LIST, or an unrecognized typeId) that the flattened sort-key encoding cannot write. Sort keys must consist of primitive-comparable types; nested types cannot be serialized into the shuffle payload.

Source

Thrown at flink/v2.3/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 to use only primitive columns (e.g., extract a primitive member of the struct as a top-level column).
2. Flatten nested data: write the desired leaf value into a primitive column and sort on that.
3. If the typeId is from a newly supported type in a newer Iceberg version, upgrade iceberg-flink-runtime to match the writer's schema handling.
4. Validate the sort order before starting the job: assert every field of the sort order is a primitive type.

Example fix

// before: sort order on struct field
SortOrder.builderFor(schema).asc("nested_struct").build();
// after: sort on a primitive column
SortOrder.builderFor(schema).asc("nested_struct_id").build();

for (SortField f : sortOrder.fields()) {
  Type t = schema.findType(f.sourceId());
  Preconditions.checkArgument(t.isPrimitiveType(),
      "Sort field %s must be primitive, found: %s", f.sourceId(), t);
}

boolean isSortKeySerializable(Schema schema, SortOrder order) {
  return order.fields().stream()
      .allMatch(f -> schema.findType(f.sourceId()).isPrimitiveType());
}

try {
  sortKeySerializer.serialize(sortKey, out);
} catch (UnsupportedOperationException e) {
  LOG.error("Sort order contains nested type: {}", e.getMessage());
  throw e;
}

When it happens

Trigger: The sort order used by the key shuffle sink includes a column of type STRUCT, MAP, or LIST, so SortKey construction encounters that typeId during serialization (also triggered via copy() in serializer snapshot handling).

Common situations: Configuring a table's sort order on a nested column or array; defining ORDER BY on a struct field and then writing through the key-aware shuffle sink; an unhandled/unknown typeId arriving from a newer schema version.

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

• Field %d has unsupported field type: %s
• Failed to serialize sort key
• Field %d has unsupported field type: %s
• Failed to serialize sort key
• Unsupported task type:

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