apache/iceberg · error · UnsupportedOperationException

Unsupported type: variant

Error message

Unsupported type: variant

What it means

SchemaWithPartnerVisitor.variant() is a hook that visitors must override to handle VariantType columns; the base class default throws UnsupportedOperationException. It signals that the current visitor was not written with Variant support in mind and encountered a variant column during schema traversal.

Source

Thrown at core/src/main/java/org/apache/iceberg/schema/SchemaWithPartnerVisitor.java:167

  public R struct(Types.StructType struct, P partner, List<R> fieldResults) {
    return null;
  }

  public R field(Types.NestedField field, P partner, R fieldResult) {
    return null;
  }

  public R list(Types.ListType list, P partner, R elementResult) {
    return null;
  }

  public R map(Types.MapType map, P partner, R keyResult, R valueResult) {
    return null;
  }

  public R variant(Types.VariantType variant, P partner) {
    throw new UnsupportedOperationException("Unsupported type: variant");
  }

  public R primitive(Type.PrimitiveType primitive, P partner) {
    return null;
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Override variant(Types.VariantType, P) in the visitor to return the appropriate result for variant columns
2. Skip or filter variant fields before visiting if they are out of scope
3. Upgrade to a newer Iceberg version where the relevant visitor implementations support Variant

Example fix

// before
class MyVisitor extends SchemaWithPartnerVisitor<Type, Type> { }
// after
class MyVisitor extends SchemaWithPartnerVisitor<Type, Type> {
  @Override
  public Type variant(Types.VariantType variant, Type partner) {
    return Types.VariantType.get();
  }
}

if (schema.columns().stream().anyMatch(c -> c.type().typeId() == Type.TypeID.VARIANT)) {
  throw new IllegalArgumentException("Schema contains variant columns");
}

boolean supportsVariant = visitorClass != null && overridesVariant(visitorClass);

try { SchemaWithPartnerVisitor.visit(schema, partner, visitor); } catch (UnsupportedOperationException e) { if (e.getMessage().contains("variant")) { /* handle variant columns */ } else throw e; }

When it happens

Trigger: Visiting a schema that contains a Types.VariantType field using a visitor that only overrides visitPrimitive/visitMap/etc. and inherits the default variant() implementation.

Common situations: Upgrading a table to format version 3 introduces variant columns, but custom visitor-based code (type rewriters, compatibility checkers, engine adapters) predates Variant support.

Related errors

• Unsupported type: variant
• Unsupported type: variant
• Unsupported type: variant
• Cannot handle
• Variant is not supported

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