apache/iceberg · error · UncheckedIOException

Failed to encode partition

Error message

Failed to encode partition

What it means

StructLikeSerializer.encodePartition converts a partition StructLike into bytes using the partition type's fields; any IOException during writing is wrapped in an UncheckedIOException with this message. It indicates partition values could not be encoded for keying/storage.

Source

Thrown at flink/v1.20/flink/src/main/java/org/apache/iceberg/flink/maintenance/operator/StructLikeSerializer.java:88

    return new SerializedEqualityValues(baos.toByteArray());
  }

  public byte[] encodePartition(StructLike partition, Types.StructType partitionType) {
    List<Types.NestedField> fields = partitionType.fields();
    if (fields.isEmpty()) {
      return EMPTY_PARTITION;
    }

    baos.reset();
    try {
      for (int i = 0; i < fields.size(); i++) {
        writeField(partition, i, fields.get(i).type());
      }

      dos.flush();
    } catch (IOException e) {
      throw new UncheckedIOException("Failed to encode partition", e);
    }

    return baos.toByteArray();
  }

  public static StructLike decodePartition(byte[] encoded, Types.StructType partitionType) {
    PartitionData partition = new PartitionData(partitionType);
    List<Types.NestedField> fields = partitionType.fields();
    if (fields.isEmpty()) {
      return partition;
    }

    try (DataInputStream dis = new DataInputStream(new ByteArrayInputStream(encoded))) {
      for (int i = 0; i < fields.size(); i++) {
        boolean isNull = dis.readBoolean();
        if (isNull) {
          partition.set(i, null);
        } else {

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Check the wrapped IOException cause and the partition type of the table.
2. Verify all partition field types are supported by the Flink sink serializer.
3. Upgrade Iceberg if a supported type fails; otherwise file a bug with the partition spec.

// Verify partition spec field types are supported before encodePartition
partitionType.fields().forEach(f -> check(supportedTypes.contains(f.type()), "Unsupported partition type: " + f.type()));

try { byte[] encoded = serializer.encodePartition(partition, partitionType); } catch (UncheckedIOException e) { LOG.error("Partition encode failed", e.getCause()); throw e; }

When it happens

Trigger: Calling encodePartition where writeField throws IOException while serializing one of the partition spec's fields (unsupported type or writer failure).

Common situations: Partition specs containing exotic types not covered by the serializer's writeField, or internal I/O errors while writing to the buffer.

Understand the failure class

Background: "JSON serialization failed", "not JSON serializable", "Failed to serialize": why JSON marshaling errors happen and how to fix them — this error's family across 46 libraries.

Related errors

• Altering partition keys is not supported yet.
• The Avro schema is not a nullable type: ${schema}
• Fail to serialize at field: %s.
• Unrecognized version or corrupt state: <version>
• Failed to serialize PK index key

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