apache/iceberg · error · UnsupportedOperationException

Unsupported codec:

Error message

Unsupported codec: 

What it means

PuffinFormat.compress only implements GZIP, ZSTD (and a stubbed LZ4 case). For any other codec (e.g. LZ4, which has no Java frame compressor wired in), it throws UnsupportedOperationException('Unsupported codec: ...') because the library cannot compress puffin blobs with that codec.

Solutions

1. Use ZSTD or GZIP compression for puffin blobs instead of LZ4
2. Omit the compression codec property to write uncompressed blobs
3. If LZ4 is required, write the blob yourself with an LZ4 frame compressor and register/produce it outside PuffinFormat, or wait for upstream LZ4 support (aircompressor PR #142)
4. Check the codec requested by your blob writer configuration and change it to a supported one

Example fix

// before
builder.compressionCodec(Lz4Compressor.class.getSimpleName()); // unsupported
// after
builder.compressionCodec("zstd"); // or "gzip" / none

Set<String> supported = Set.of("gzip", "zstd");
if (codec != null && !supported.contains(codec.toLowerCase(Locale.ROOT))) {
  throw new IllegalArgumentException("Codec not supported for puffin: " + codec);
}

try {
  writeBlob(input, codec);
} catch (UnsupportedOperationException e) {
  writeBlob(input, "zstd"); // fall back to a supported codec
}

When it happens

Trigger: Writing puffin files (e.g. deletion vectors / blob stats) with blob properties requesting LZ4 or another codec that PuffinFormat cannot compress; configuring a writer to emit a compression codec not in {gzip, zstd}.

Common situations: Specs/tools expecting LZ4-compressed puffin blobs (LZ4 frame compression is still unimplemented, per the TODO referencing airlift aircompressor PR #142); copying compression settings from another engine that supports LZ4.

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

• Invalid file: expected magic at offset
• Unsupported compression codec:
• Unsupported compression codec
• Unsupported compression strategy:
• Unsupported flag:

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

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/puffin/PuffinFormat.java:117

  static int readIntegerLittleEndian(byte[] data, int offset) {
    return Byte.toUnsignedInt(data[offset])
        | (Byte.toUnsignedInt(data[offset + 1]) << 8)
        | (Byte.toUnsignedInt(data[offset + 2]) << 16)
        | (Byte.toUnsignedInt(data[offset + 3]) << 24);
  }

  static ByteBuffer compress(PuffinCompressionCodec codec, ByteBuffer input) {
    switch (codec) {
      case NONE:
        return input.duplicate();
      case LZ4:
        // TODO requires LZ4 frame compressor, e.g.
        // https://github.com/airlift/aircompressor/pull/142
        break;
      case ZSTD:
        return compress(new ZstdCompressor(), input);
    }
    throw new UnsupportedOperationException("Unsupported codec: " + codec);
  }

  private static ByteBuffer compress(Compressor compressor, ByteBuffer input) {
    ByteBuffer output = ByteBuffer.allocate(compressor.maxCompressedLength(input.remaining()));
    compressor.compress(input.duplicate(), output);
    output.flip();
    return output;
  }

  static ByteBuffer decompress(PuffinCompressionCodec codec, ByteBuffer input) {
    switch (codec) {
      case NONE:
        return input.duplicate();

      case LZ4:
        // TODO requires LZ4 frame decompressor, e.g.
        // https://github.com/airlift/aircompressor/pull/142
        break;

View on GitHub (pinned to 86d9c8fc54)