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

Check type.isPrimitiveType() (or instanceof Type.PrimitiveType) before calling asPrimitiveType().

Not a primitive type: + this

Error message

Not a primitive type: + this

What it means

Type.asPrimitiveType() is a narrowing convenience on Iceberg's Type interface. The default implementation throws IllegalArgumentException because most Type instances (struct, list, map, variant) are not primitives. Only PrimitiveType subtypes override it to return this.

Solutions

Check type.isPrimitiveType() (or instanceof Type.PrimitiveType) before calling asPrimitiveType().
Dispatch via a TypeVisitor (TypeUtil.visit) instead of manual narrowing.
Fix logic that selected the wrong field/type — e.g. iterate only primitive fields when narrowing.

Example fix

// before
Types.NestedField f = schema.findField("location");
Type.PrimitiveType p = f.type().asPrimitiveType();
// after
Types.NestedField f = schema.findField("location");
if (f.type().isPrimitiveType()) {
  Type.PrimitiveType p = f.type().asPrimitiveType();
}

Defensive patterns

Strategy: type-guard

Validate before calling

Preconditions.checkArgument(type.isPrimitiveType(), "Expected primitive, got: %s", type);

Type guard

if (type.isPrimitiveType()) {
  Type.PrimitiveType p = type.asPrimitiveType();
}

Try / catch

try {
  Type.PrimitiveType p = type.asPrimitiveType();
} catch (IllegalArgumentException e) {
  // handle non-primitive branch
}

Prevention

Check isPrimitiveType() before every asPrimitiveType() call.
Prefer TypeVisitor dispatch over manual type narrowing.
Don't assume flat schemas — Iceberg types are arbitrarily nested.

When it happens

Trigger: Calling asPrimitiveType() on any Type that is not a PrimitiveType, e.g. type.asPrimitiveType() after finding a field whose result type is a StructType or ListType, or on TypeUtil.visit results typed as Type.

Common situations: Generic schema-walking code that assumes all columns are primitives (Avro/Parquet-style flat schemas); partition or metrics code that blindly narrows field types; migrating code from engines where all column types were primitive.

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

Appendix: source

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

    private final Class<?> javaClass;

    TypeID(Class<?> javaClass) {
      this.javaClass = javaClass;
    }

    public Class<?> javaClass() {
      return javaClass;
    }
  }

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

View on GitHub (pinned to 86d9c8fc54)