apache/iceberg · error · IllegalArgumentException

Not an object:

Error message

Not an object: 

What it means

VariantValue.asObject() is a default downcast helper; the interface implementation always throws this IllegalArgumentException because only VariantObject instances are objects. The caller assumed an object value but the variant is a primitive or array.

Solutions

1. Verify the value's basic type is OBJECT (or use instanceof VariantObject) before calling asObject()
2. Handle primitive/array values explicitly
3. Catch IllegalArgumentException and branch on the actual type

Example fix

// before
VariantObject obj = value.asObject();
// after
if (value instanceof VariantObject) {
  VariantObject obj = (VariantObject) value;
} else {
  throw new IllegalStateException("expected object, got " + value.type());
}

if (!(value instanceof VariantObject)) {
  throw new IllegalStateException("expected object variant, got " + value.type());
}

if (value instanceof VariantObject) { VariantObject o = (VariantObject) value; }

try {
  VariantObject o = value.asObject();
} catch (IllegalArgumentException e) {
  // handle primitive/array case
}

When it happens

Trigger: Calling asObject() on a VariantValue that is not a VariantObject — e.g. iterating object fields with cursor()/obj() against an array or primitive, or expectedObject validation failing on actual data.

Common situations: Assuming nested variant data is an object when it is an array; data drift where the stored shape changed; missing type check before traversal.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Not a primitive:
• Not an array:
• Cannot use catalog ( ): not a TableCatalog
• Cannot use non-v1 table
• Metadata is required for object:

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

Appendix: source

Thrown at api/src/main/java/org/apache/iceberg/variants/VariantValue.java:51

   */
  int writeTo(ByteBuffer buffer, int offset);

  /**
   * Returns this value as a {@link VariantPrimitive}.
   *
   * @throws IllegalArgumentException if the value is not a primitive
   */
  default VariantPrimitive<?> asPrimitive() {
    throw new IllegalArgumentException("Not a primitive: " + this);
  }

  /**
   * Returns this value as a {@link VariantObject}.
   *
   * @throws IllegalArgumentException if the value is not an object
   */
  default VariantObject asObject() {
    throw new IllegalArgumentException("Not an object: " + this);
  }

  /**
   * Returns this value as a {@link VariantArray}.
   *
   * @throws IllegalArgumentException if the value is not an array
   */
  default VariantArray asArray() {
    throw new IllegalArgumentException("Not an array: " + this);
  }

  static VariantValue from(VariantMetadata metadata, ByteBuffer value) {
    return VariantUtil.fromBuffer(metadata, value, 0);
  }
}

View on GitHub (pinned to 86d9c8fc54)