apache/iceberg · error · UnsupportedOperationException

does not support serialize

Error message

${getClass().getName()} does not support serialize

What it means

PositionDeleteIndex.serialize() converts the index into a serialized ByteBuffer; the interface default throws UnsupportedOperationException because serialization is only meaningful for implementations with a binary encoding (e.g. Roaring bitmaps). Callers such as toBlob, bytes, and buffer invoke it when persisting indexes (e.g. in deletion vectors).

Solutions

1. Implement serialize() to write a binary representation (and matching deserialize) in the implementation
2. Use BitmapPositionDeleteIndex, whose serialize() produces the standard Roaring-bitmap encoding
3. Do not route non-encodable indexes into deletion-vector/persisted-blob code paths

Example fix

// before
@Override public ByteBuffer serialize() { throw new UnsupportedOperationException(...); }
// after
@Override public ByteBuffer serialize() { return bitmap.toByteBuffer(); }

if (index instanceof BitmapPositionDeleteIndex) { ByteBuffer buf = index.serialize(); } else { throw new IllegalStateException("Index has no binary encoding"); }

boolean supportsSerialize(PositionDeleteIndex idx) { return idx instanceof BitmapPositionDeleteIndex; }

try { ByteBuffer buf = index.serialize(); } catch (UnsupportedOperationException e) { throw new IllegalStateException("Cannot persist this index type", e); }

When it happens

Trigger: Calling serialize() (directly or via toBlob/bytes/buffer helpers) on an implementation that has not overridden the default method.

Common situations: A custom PositionDeleteIndex implementation being written into a deletion vector blob or Puffin file, without a binary encoding defined.

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

• Cannot serialize type: + typeId
• Failed to encode value as UTF-8
• does not implement length
• does not support cardinality
• does not support forEach

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

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/deletes/PositionDeleteIndex.java:102

   *
   * @return delete files that this index was created from
   */
  default Collection<DeleteFile> deleteFiles() {
    return ImmutableList.of();
  }

  /** Returns the cardinality of this index. */
  default long cardinality() {
    throw new UnsupportedOperationException(getClass().getName() + " does not support cardinality");
  }

  /**
   * Serializes this index.
   *
   * @return a buffer containing the serialized index
   */
  default ByteBuffer serialize() {
    throw new UnsupportedOperationException(getClass().getName() + " does not support serialize");
  }

  /**
   * Deserializes a position delete index.
   *
   * @param bytes an array containing the serialized index
   * @param deleteFile the delete file that the index is created for
   * @return the deserialized index
   */
  static PositionDeleteIndex deserialize(byte[] bytes, DeleteFile deleteFile) {
    return BitmapPositionDeleteIndex.deserialize(bytes, deleteFile);
  }

  /** Returns an empty immutable position delete index. */
  static PositionDeleteIndex empty() {
    return EmptyPositionDeleteIndex.get();
  }
}

View on GitHub (pinned to 86d9c8fc54)