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

Guard with type.isStructType() or instanceof Types.StructType before narrowing.

Not a struct type: + this

Error message

Not a struct type: + this

What it means

Type.asStructType() narrows a Type to Types.StructType; the default implementation throws IllegalArgumentException because only struct types override it. It signals that the code attempted struct-level access (fields()) on a non-struct type.

Solutions

Guard with type.isStructType() or instanceof Types.StructType before narrowing.
Use TypeUtil.visit / TypeVisitor to handle each type kind explicitly.
Correct the field path or schema assumption that led to a non-struct type.

Example fix

// before
Types.StructType st = schema.asStruct().field("tags").type().asStructType();
// after
Type tags = schema.asStruct().field("tags").type();
Types.StructType st = tags instanceof Types.StructType ? (Types.StructType) tags : null;

Defensive patterns

Strategy: type-guard

Validate before calling

Preconditions.checkArgument(type.isStructType(), "Expected struct, got: %s", type);

Type guard

if (type instanceof Types.StructType) {
  Types.StructType st = (Types.StructType) type;
}

Try / catch

try {
  Types.StructType st = type.asStructType();
} catch (IllegalArgumentException e) {
  // non-struct path
}

Prevention

Use instanceof Types.StructType checks before struct access.
Handle all nested kinds (struct/list/map/variant) in traversal code.
Re-verify assumptions after schema evolution changes field types.

When it happens

Trigger: Calling asStructType() on a ListType, MapType, primitive, or VariantType — commonly inside projection, select, project, or reassignIds-style logic that assumed a field's type was a struct.

Common situations: Building row projections where a column is actually a list/map at the top level; visitor code handling nested types without checking the kind; renaming/refactoring that changed a field from struct to list.

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

Appendix: source

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

    }

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

  default boolean isNestedType() {
    return false;
  }

View on GitHub (pinned to 86d9c8fc54)