What causes "Not a variant type: + this" in apache/iceberg?

Check type.isVariantType() before calling asVariantType().

Not a variant type: + this

Error message

Not a variant type: + this

What it means

Type.asVariantType() narrows a Type to Types.VariantType; the default throws IllegalArgumentException because only VariantType overrides it. Variant is a special nested type, so narrowing fails for every other Type.

Solutions

Check type.isVariantType() before calling asVariantType().
Update visitors/handlers to support VariantType (requires Iceberg format supporting variants).
Filter variant columns out before generic type processing if unsupported.

Example fix

// before
Types.VariantType vt = field.type().asVariantType();
// after
if (field.type().isVariantType()) {
  Types.VariantType vt = Types.VariantType.get();
}

Defensive patterns

Strategy: type-guard

Validate before calling

Preconditions.checkArgument(type.isVariantType(), "Expected variant, got: %s", type);

Type guard

if (type.isVariantType()) {
  Types.VariantType vt = Types.VariantType.get();
}

Try / catch

try {
  Types.VariantType vt = type.asVariantType();
} catch (IllegalArgumentException e) {
  // non-variant path
}

Prevention

Check isVariantType() before narrowing.
Update visitors and type converters to handle VariantType.
Gate variant support on engine/client capability before processing such tables.

When it happens

Trigger: Calling asVariantType() on any non-variant Type — typically in generic visitor code (visit) that handles all nested kinds and calls each asXxxType unconditionally.

Common situations: Visitor implementations written before the Variant type existed that now encounter variant columns; code inspecting metadata/physics columns where variant type appears unexpectedly; older clients reading tables containing variant columns.

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

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

Appendix: source

Thrown at api/src/main/java/org/apache/iceberg/types/Type.java:89

  default PrimitiveType asPrimitiveType() {
    throw new IllegalArgumentException("Not a primitive type: " + this);
  }

  default Types.StructType asStructType() {
    throw new IllegalArgumentException("Not a struct type: " + this);
  }

  default Types.ListType asListType() {
    throw new IllegalArgumentException("Not a list type: " + this);
  }

  default Types.MapType asMapType() {
    throw new IllegalArgumentException("Not a map type: " + this);
  }

  default Types.VariantType asVariantType() {
    throw new IllegalArgumentException("Not a variant type: " + this);
  }

  default boolean isNestedType() {
    return false;
  }

  default boolean isStructType() {
    return false;
  }

  default boolean isListType() {
    return false;
  }

  default boolean isMapType() {
    return false;
  }

View on GitHub (pinned to 86d9c8fc54)