apache/iceberg · error · IllegalArgumentException

Not a primitive:

Error message

Not a primitive: 

What it means

VariantValue.asPrimitive() is a default downcast helper; the base interface's implementation always throws this IllegalArgumentException because only VariantPrimitive instances are primitives. It signals a caller assumed a value was a primitive when it is an object or array.

Solutions

1. Check value.type() / basic type is PRIMITIVE before calling asPrimitive()
2. Handle the object/array cases explicitly in the calling code
3. Catch IllegalArgumentException from asPrimitive() and branch accordingly

Example fix

// before
VariantPrimitive<?> p = value.asPrimitive();
// after
if (value instanceof VariantPrimitive) {
  VariantPrimitive<?> p = (VariantPrimitive<?>) value;
} else {
  // handle object/array case
}

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

if (value instanceof VariantPrimitive) { VariantPrimitive<?> p = (VariantPrimitive<?>) value; }

try {
  VariantPrimitive<?> p = value.asPrimitive();
} catch (IllegalArgumentException e) {
  // handle object/array case
}

When it happens

Trigger: Calling asPrimitive() on a VariantValue that is actually a VariantObject or VariantArray (e.g. after VariantValue.from without checking basicType), from code paths like castTo, buffer, decimalValue, or sanitizeVariant operating on non-primitive values.

Common situations: Assuming a variant field holds a scalar when it actually holds nested data; schema changed so a previously-primitive column now stores objects/arrays; missing isPrimitive()/type() check before downcasting.

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 an array:
• 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/2a0754b573f62044. Report an issue: GitHub.

Appendix: source

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

public interface VariantValue {
  /** Returns the {@link PhysicalType} of this value. */
  PhysicalType type();

  /** Returns the serialized size in bytes of this value. */
  int sizeInBytes();

  /**
   * Writes this value to the buffer at the given offset, ignoring the buffer's position and limit.
   */
  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);

View on GitHub (pinned to 86d9c8fc54)