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

Check type.isMapType() or instanceof Types.MapType before narrowing.

Not a map type: + this

Error message

Not a map type: + this

What it means

Default guard on Type.asMapType: the receiver is not a Types.MapType, so the cast-style conversion is refused. The concatenated 'this' in the message is the actual type. It fires when code assumes a map type without checking typeId()/isMapType() first — the fault is the unguarded downcast on the caller's side.

Solutions

Check type.isMapType() or instanceof Types.MapType before narrowing.
Dispatch with a TypeVisitor instead of chained asXxxType calls.
Verify the schema/field reference actually points to the map type.

Example fix

// before
Types.MapType mt = field.type().asMapType();
// after
if (field.type() instanceof Types.MapType) {
  Types.MapType mt = (Types.MapType) field.type();
}

Defensive patterns

Strategy: type-guard

Validate before calling

Preconditions.checkArgument(type.isMapType(), "Expected map, got: %s", type);

Type guard

if (type instanceof Types.MapType) {
  Types.MapType mt = (Types.MapType) type;
}

Try / catch

try {
  Types.MapType mt = type.asMapType();
} catch (IllegalArgumentException e) {
  // non-map path
}

Prevention

Check isMapType() before key/value access.
Branch per type kind in generic schema walkers.
Validate engine-to-Iceberg type mapping for map columns.

When it happens

Trigger: Calling asMapType() on struct, list, primitive, or variant types — e.g. via mapType/keyType/valueType helpers or map partner lookups in TypeUtil visitor plumbing when the field type is not a map.

Common situations: Reading key/value nested IDs for a column that is actually a list or struct; generic column-pruning code assuming map semantics; engine type conversion that mapped a map column to the wrong Iceberg type.

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

Appendix: source

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

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

  default boolean isListType() {
    return false;
  }

View on GitHub (pinned to 86d9c8fc54)