apache/iceberg · error · IllegalArgumentException

Cannot delete element type from list:

Error message

Cannot delete element type from list: 

What it means

During SchemaUpdate.apply, a TypeUtil visitor rebuilds the schema; for a list type it recursively resolves the element type via field(). If field() returns null — meaning the element field is being deleted (it is in the deletes set) — this IllegalArgumentException is thrown, because deleting a list's element type outright is not a supported schema update.

Source

Thrown at core/src/main/java/org/apache/iceberg/SchemaUpdate.java:695

        // if either collection is non-null, then this must be a struct type. try to apply the
        // changes
        List<Types.NestedField> fields =
            addAndMoveFields(fieldResult.asStructType().fields(), newFields, columnsToMove);
        if (fields != null) {
          return Types.StructType.of(fields);
        }
      }

      return fieldResult;
    }

    @Override
    public Type list(Types.ListType list, Type elementResult) {
      // use field to apply updates
      Types.NestedField elementField = list.fields().get(0);
      Type elementType = field(elementField, elementResult);
      if (elementType == null) {
        throw new IllegalArgumentException("Cannot delete element type from list: " + list);
      }

      Types.NestedField elementUpdate = updates.get(elementField.fieldId());
      boolean isElementOptional =
          elementUpdate != null ? elementUpdate.isOptional() : list.isElementOptional();

      if (isElementOptional == elementField.isOptional() && list.elementType() == elementType) {
        return list;
      }

      if (isElementOptional) {
        return Types.ListType.ofOptional(list.elementId(), elementType);
      } else {
        return Types.ListType.ofRequired(list.elementId(), elementType);
      }
    }

    @Override

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Delete the top-level list column by its own field ID instead of the element field ID
2. If the intent is to replace the element type, use updateSchema.updateColumn(...)/addElement/requireElement rather than delete
3. Filter generated delete sets to exclude nested list element field IDs

Example fix

// before
int elementId = listType.fields().get(0).fieldId();
updateSchema.delete(elementId); // throws
// after
updateSchema.delete(listColumnFieldId); // delete the list column itself

Set<Integer> deletable = new HashSet<>();
schema.columns().forEach(f -> collectDeletableIds(f, deletable));
static void collectDeletableIds(Types.NestedField f, Set<Integer> out) {
  out.add(f.fieldId());
  if (f.type() instanceof Types.StructType) f.type().asStructType().fields().forEach(c -> collectDeletableIds(c, out));
  // note: list element and map key/value ids are NOT added
}

static boolean isListElementId(Schema schema, int fieldId) {
  return schema.columns().stream().flatMap(f -> nestedTypes(f.type()).stream())
      .anyMatch(t -> t instanceof Types.ListType && t.asListType().fields().get(0).fieldId() == fieldId);
}

try {
  updateSchema.apply();
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Cannot delete element type")) throw new IllegalStateException("Delete the list column, not its element field", e);
  throw e;
}

When it happens

Trigger: Calling schema.update(...) / updateSchema.delete(elementFieldId) where elementFieldId is the list element field's ID (the nested field id of the list element), attempting to delete the element of a list column.

Common situations: Tooling that enumerates all nested field IDs and issues deletes for them, accidentally including list element IDs; users intending to drop the whole list column but targeting the element field id instead of the column's top-level id.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Cannot delete map keys:
• Cannot update map keys:
• Cannot add fields to map keys:
• Cannot alter map keys:
• Unsorted order ID must be 0

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