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

Check type.isListType() before calling asListType().

Not a list type: + this

Error message

Not a list type: + this

What it means

Type.asListType() narrows a Type to Types.ListType; the default throws IllegalArgumentException since non-list types do not override it. It indicates list-element access (elementType()) was requested on a type that is not a list.

Solutions

Check type.isListType() before calling asListType().
Use a TypeVisitor to branch per type kind.
Fix ID/partner lookups so the element type is fetched from the actual list field.

Example fix

// before
Types.ListType lt = field.type().asListType();
// after
if (field.type() instanceof Types.ListType) {
  Types.ListType lt = (Types.ListType) field.type();
}

Defensive patterns

Strategy: type-guard

Validate before calling

Preconditions.checkArgument(type.isListType(), "Expected list, got: %s", type);

Type guard

if (type instanceof Types.ListType) {
  Types.ListType lt = (Types.ListType) type;
}

Try / catch

try {
  Types.ListType lt = type.asListType();
} catch (IllegalArgumentException e) {
  // non-list path
}

Prevention

Check isListType() before element access.
Fetch element types via the actual list field, not by ID/name assumptions.
Use TypeVisitor so each type kind is handled explicitly.

When it happens

Trigger: Calling asListType() on a struct, map, primitive, or variant — e.g. in visitor helpers (listType, elementType, listElementPartner) or when reading a list column whose field resolved to a different type.

Common situations: Handling nested element IDs where the referenced type is actually a map or struct; schema iteration code that assumes a field named 'element' is always a list; mapping Iceberg list columns to engine types incorrectly.

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/c09d93d402ef3a31. Report an issue: GitHub.

Appendix: source

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

    }
  }

  TypeID typeId();

  default boolean isPrimitiveType() {
    return false;
  }

  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;
  }

View on GitHub (pinned to 86d9c8fc54)