apache/iceberg · error · UnsupportedOperationException

Unsupported basic type:

Error message

Unsupported basic type: 

What it means

VariantUtil.fromBuffer dispatches a serialized variant value by its basic type header (primitive, object, array). A header byte whose basic type is not one of the known values triggers this UnsupportedOperationException, i.e. the value buffer is malformed or uses an unrecognized basic type.

Solutions

1. Upgrade Iceberg to a version that recognizes the basic type code
2. Verify the value buffer's header byte is valid before decoding
3. Re-write corrupted variant data from a trusted source

int basicBits = (header & 0x03);
if (basicBits > 2) { throw new IllegalStateException("invalid variant basic type bits: " + basicBits); }

try {
  VariantValue v = VariantValue.from(metadata, buffer);
} catch (UnsupportedOperationException e) {
  // treat buffer as corrupt; quarantine or re-write
}

When it happens

Trigger: Calling VariantUtil.fromBuffer (or VariantValue.from) on a buffer whose header byte encodes a basic type outside {PRIMITIVE, OBJECT, ARRAY}; corrupted values or newer-spec headers.

Common situations: Corrupted data files; reading variants written by newer writers; manual buffer construction with wrong header byte (e.g. header from a large-size variant encoded incorrectly).

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Cannot convert JSON to literal: " + node
• Cannot deserialize type: + type
• Cannot parse reference (requires string or object): " + node
• Cannot parse type as a reference: " + type
• Cannot parse type from json:

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

Appendix: source

Thrown at api/src/main/java/org/apache/iceberg/variants/VariantUtil.java:71

        depth <= MAX_VARIANT_DEPTH,
        "Invalid variant: nesting depth %s exceeds maximum %s",
        depth,
        MAX_VARIANT_DEPTH);
    Preconditions.checkArgument(value.remaining() >= 1, "Invalid variant: empty value buffer");
    int header = ByteBuffers.readByte(value, 0);
    BasicType basicType = basicType(header);
    switch (basicType) {
      case PRIMITIVE:
        return SerializedPrimitive.from(value, header);
      case SHORT_STRING:
        return SerializedShortString.from(value, header);
      case OBJECT:
        return SerializedObject.from(metadata, value, header, depth);
      case ARRAY:
        return SerializedArray.from(metadata, value, header, depth);
    }

    throw new UnsupportedOperationException("Unsupported basic type: " + basicType);
  }

  static float readFloat(ByteBuffer buffer, int offset) {
    return buffer.getFloat(buffer.position() + offset);
  }

  static double readDouble(ByteBuffer buffer, int offset) {
    return buffer.getDouble(buffer.position() + offset);
  }

  static ByteBuffer slice(ByteBuffer buffer, int offset, int length) {
    ByteBuffer slice = buffer.duplicate();
    slice.order(ByteOrder.LITTLE_ENDIAN);
    slice.position(buffer.position() + offset);
    slice.limit(buffer.position() + offset + length);
    return slice;
  }

View on GitHub (pinned to 86d9c8fc54)