apache/iceberg · error · IllegalArgumentException

Not an array:

Error message

Not an array: 

What it means

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

Solutions

1. Verify the value's basic type is ARRAY (or use instanceof VariantArray) before calling asArray()
2. Handle primitive/object values explicitly in the caller
3. Catch IllegalArgumentException and branch on the actual type

Example fix

// before
VariantArray arr = value.asArray();
// after
if (value instanceof VariantArray) {
  VariantArray arr = (VariantArray) value;
} else {
  throw new IllegalStateException("expected array, got " + value.type());
}

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

if (value instanceof VariantArray) { VariantArray a = (VariantArray) value; }

try {
  VariantArray a = value.asArray();
} catch (IllegalArgumentException e) {
  // handle primitive/object case
}

When it happens

Trigger: Calling asArray() on a VariantValue that is not a VariantArray — e.g. cursor()/array element traversal over an object or primitive, or expectedArray validation on mismatched data.

Common situations: Assuming a variant holds a list when it holds a scalar; data shape changed between writer versions; missing is-array check before iterating elements.

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 object:
• 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/c6418f41a04ec8b5. Report an issue: GitHub.

Appendix: source

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

    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)