apache/iceberg · error · UnsupportedOperationException

Not implemented for variant

Error message

Not implemented for variant

What it means

ParquetWithSparkSchemaVisitor.variant is the hook for visiting Spark VariantType columns backed by Parquet groups; the base implementation unconditionally throws UnsupportedOperationException so subclasses must override it. Hitting this means a variant column was visited but the concrete visitor didn't implement variant handling.

Source

Thrown at spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/data/ParquetWithSparkSchemaVisitor.java:236

  public T struct(StructType sStruct, GroupType struct, List<T> fields) {
    return null;
  }

  public T list(ArrayType sArray, GroupType array, T element) {
    return null;
  }

  public T map(MapType sMap, GroupType map, T key, T value) {
    return null;
  }

  public T primitive(DataType sPrimitive, PrimitiveType primitive) {
    return null;
  }

  public T variant(VariantType sVariant, GroupType variant) {
    throw new UnsupportedOperationException("Not implemented for variant");
  }

  protected String[] currentPath() {
    return Lists.newArrayList(fieldNames.descendingIterator()).toArray(new String[0]);
  }

  protected String[] path(String name) {
    List<String> list = Lists.newArrayList(fieldNames.descendingIterator());
    list.add(name);
    return list.toArray(new String[0]);
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Upgrade to an Iceberg version where the specific visitor implements variant support.
  2. Exclude variant columns from the operation (e.g. filter them out of the rewrite/read projection).
  3. If you own the visitor subclass, override variant(VariantType, GroupType) to return a proper handler.

Example fix

// before
new MyVisitor() { ... } // variant() not overridden
// after
@Override
public T variant(VariantType sVariant, GroupType variant) {
  return buildVariantReader(variant); // implement handling
}
Defensive patterns

Strategy: type-guard

Validate before calling

boolean hasVariant = table.schema().columns().stream().anyMatch(f -> f.type().typeId() == Types.VariantType.get().typeId());

Type guard

if (type instanceof VariantType) { /* ensure the concrete visitor overrides variant() before proceeding */ }

Try / catch

try { visitor.primitive(schema, primitive); } catch (UnsupportedOperationException e) { if (e.getMessage().equals("Not implemented for variant")) { /* skip/projection-exclude variant columns */ } else throw e; }

Prevention

When it happens

Trigger: A Parquet read path using ParquetWithSparkSchemaVisitor encounters a Spark VariantType field (three-group variant Parquet layout) while the concrete visitor (e.g. a Parquet value-writer/converter) has no variant() override.

Common situations: Reading or rewriting tables containing variant-typed columns with a code path that predates variant support (older runtime or a visitor subclass that never implemented it).

Related errors

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