apache/iceberg · error · UnsupportedOperationException

Not implemented for variant

Error message

Not implemented for variant

What it means

The default SparkTypeVisitor.variant implementation throws 'Not implemented for variant': subclasses of SparkTypeVisitor are expected to override variant(VariantType) to handle Spark VariantType, and the base class provides no meaningful default. Calling the base implementation (i.e., using a visitor that did not override it) on a schema containing VariantType columns raises UnsupportedOperationException.

Solutions

  1. Override variant(VariantType) in your SparkTypeVisitor subclass and return an appropriate result
  2. Filter or reject VariantType columns before traversing if your use case cannot handle them
  3. If the visitor is library-provided and you only read schemas without variants, strip Variant columns from the schema first

Example fix

// before
SparkTypeVisitor<String> visitor = new SparkTypeVisitor<String>() {}; // variant() not overridden
// after
SparkTypeVisitor<String> visitor = new SparkTypeVisitor<String>() {
  @Override
  public String variant(VariantType variant) { return "variant"; }
};
Defensive patterns

Strategy: type-guard

Validate before calling

static boolean hasVariant(StructType schema) {
  return java.util.Arrays.stream(schema.fields())
      .anyMatch(f -> f.dataType() instanceof VariantType);
}

Type guard

if (sparkType instanceof VariantType && visitorHandlesVariant) { visitor.variant((VariantType) sparkType); }

Try / catch

try {
  return SparkTypeVisitor.visit(type, visitor);
} catch (UnsupportedOperationException e) {
  if ("Not implemented for variant".equals(e.getMessage())) { return fallbackForVariant(type); }
  throw e;
}

Prevention

When it happens

Trigger: Traversing a Spark schema containing a VariantType column with a SparkTypeVisitor subclass that has not overridden variant(), so the base-class stub executes and throws.

Common situations: Writing custom type-traversal utilities for schemas containing the newer Spark/Iceberg Variant type; forgetting to update an existing visitor subclass after Variant support was introduced in the schema.

Related errors

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

Appendix: source

Thrown at spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/SparkTypeVisitor.java:64

          visit(((MapType) type).keyType(), visitor),
          visit(((MapType) type).valueType(), visitor));

    } else if (type instanceof ArrayType) {
      return visitor.array((ArrayType) type, visit(((ArrayType) type).elementType(), visitor));

    } else if (type instanceof VariantType) {
      return visitor.variant((VariantType) type);

    } else if (type instanceof UserDefinedType) {
      throw new UnsupportedOperationException("User-defined types are not supported");

    } else {
      return visitor.atomic(type);
    }
  }

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

  public T struct(StructType struct, List<T> fieldResults) {
    return null;
  }

  public T field(StructField field, T typeResult) {
    return null;
  }

  public T array(ArrayType array, T elementResult) {
    return null;
  }

  public T map(MapType map, T keyResult, T valueResult) {
    return null;
  }

View on GitHub (pinned to 86d9c8fc54)