apache/iceberg · error · UnsupportedOperationException

Variant is not supported

Error message

Variant is not supported

What it means

OrcSchemaVisitor's variant() callback is a default hook for ORC variant types; the base-class default unconditionally throws UnsupportedOperationException. Visitors that do not override variant() will throw when the visited ORC schema contains a variant type.

Source

Thrown at orc/src/main/java/org/apache/iceberg/orc/OrcSchemaVisitor.java:195

  public void afterValueField(TypeDescription value) {
    afterField(valueName(), value);
  }

  public T record(TypeDescription record, List<String> names, List<T> fields) {
    return null;
  }

  public T list(TypeDescription array, T element) {
    return null;
  }

  public T map(TypeDescription map, T key, T value) {
    return null;
  }

  public T variant(TypeDescription variant, T metadata, T value) {
    throw new UnsupportedOperationException("Variant is not supported");
  }

  public T primitive(TypeDescription primitive) {
    return null;
  }

  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 whose ORC visitor supports variant columns, if available.
  2. Store the table with Parquet or Avro instead of ORC if variant columns are required.
  3. If you implement a custom OrcSchemaVisitor, override variant() to return a value instead of relying on the throwing default.
  4. Drop or migrate variant columns in ORC-backed tables.

Example fix

// before: custom visitor relies on default
// after
@Override
public T variant(TypeDescription variant, T metadata, T value) {
  return null; // or handle metadata/value children
}
Defensive patterns

Strategy: try-catch

Validate before calling

if (schema.findSubtype("variant", true) != null) { /* schema contains variant; ensure visitor supports it or skip */ }

Try / catch

try { result = OrcSchemaVisitor.visit(schema, visitor); } catch (UnsupportedOperationException e) { if (e.getMessage().contains("Variant is not supported")) { fallbackWithoutVariant(schema); } else throw e; }

Prevention

When it happens

Trigger: OrcSchemaVisitor.visitVariant dispatches to visitor.variant() on a schema containing an ORC variant type, and the concrete visitor (e.g. StatsColumnsVisitor, ID mapper) has not overridden variant().

Common situations: Reading or writing Iceberg tables with variant columns through the ORC file format; running metadata operations (metrics collection, schema mapping) over a schema containing VariantType.

Related errors

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