apache/iceberg · error · UnsupportedOperationException

Metadata is required for object:

Error message

Metadata is required for object: 

What it means

Variants.object(VariantMetadata, VariantObject) adapts an existing variant object into a ShreddedObject, which requires its associated metadata. When the passed object implements neither VariantObject with retrievable metadata (falls through both known branches), the library throws UnsupportedOperationException stating metadata is required — shredded objects cannot function without metadata.

Solutions

1. Pass only ShreddedObject or SerializedObject instances (obtained from variant APIs) to Variants.object
2. Provide metadata explicitly via the overload that accepts VariantMetadata
3. Extend/update the library if a new object type must be supported

Example fix

// before
Variants.object(customObject);
// after
Variants.object(metadata, customObject); // explicit metadata overload

Preconditions.checkNotNull(metadata, "Variant metadata is required"); if (!(object instanceof ShreddedObject) && !(object instanceof SerializedObject)) { throw new IllegalArgumentException("Object must be a ShreddedObject or SerializedObject"); }

boolean hasMetadata(Object o) { return o instanceof ShreddedObject || o instanceof SerializedObject; }

try { return Variants.object(obj); } catch (UnsupportedOperationException e) { return Variants.object(metadata, obj); }

When it happens

Trigger: Calling Variants.object() with an object that is not a ShreddedObject or SerializedObject (i.e. a custom VariantObject implementation), or one whose metadata() returns unusable metadata.

Common situations: Custom VariantObject implementations passed into variant shredding utilities; refactoring that introduced a new object type not yet handled by Variants.object.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Cannot create namespace " + namespace + ": metadata is not…
• Encountered invalid summary for snapshot
• Entries must have explicit snapshot ids if inherited…
• Failed to commit updates to table
• Failed to read file

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

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/variants/Variants.java:120

    return VariantValue.from(metadata, value);
  }

  public static ShreddedObject object(VariantMetadata metadata, VariantObject object) {
    return new ShreddedObject(metadata, object);
  }

  public static ShreddedObject object(VariantMetadata metadata) {
    return new ShreddedObject(metadata);
  }

  public static ShreddedObject object(VariantObject object) {
    if (object instanceof ShreddedObject) {
      return new ShreddedObject(((ShreddedObject) object).metadata(), object);
    } else if (object instanceof SerializedObject) {
      return new ShreddedObject(((SerializedObject) object).metadata(), object);
    }

    throw new UnsupportedOperationException("Metadata is required for object: " + object);
  }

  public static boolean isNull(ByteBuffer valueBuffer) {
    return ByteBuffers.readByte(valueBuffer, 0) == 0;
  }

  public static ValueArray array() {
    return new ValueArray();
  }

  public static <T> VariantPrimitive<T> of(PhysicalType type, T value) {
    return new PrimitiveWrapper<>(type, value);
  }

  public static VariantPrimitive<Void> ofNull() {
    return new PrimitiveWrapper<>(PhysicalType.NULL, null);
  }

View on GitHub (pinned to 86d9c8fc54)