{"record":{"id":"f423aef910d56ae4","repo":"apache/iceberg","slug":"unsupported-type-variant-f423ae","errorCode":null,"errorMessage":"Unsupported type: variant","messagePattern":"Unsupported type: variant","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/avro/AvroSchemaVisitor.java","lineNumber":119,"sourceCode":"\n  public T record(Schema record, List<String> names, List<T> fields) {\n    return null;\n  }\n\n  public T union(Schema union, List<T> options) {\n    return null;\n  }\n\n  public T array(Schema array, T element) {\n    return null;\n  }\n\n  public T map(Schema map, T value) {\n    return null;\n  }\n\n  public T variant(Schema variant, T metadataResult, T valueResult) {\n    throw new UnsupportedOperationException(\"Unsupported type: variant\");\n  }\n\n  public T primitive(Schema primitive) {\n    return null;\n  }\n}\n","sourceCodeStart":101,"sourceCodeEnd":126,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/avro/AvroSchemaVisitor.java#L101-L126","documentation":"AvroSchemaVisitor.variant is the hook invoked when the visitor encounters an Iceberg Variant type in an Avro schema. The base implementation throws UnsupportedOperationException because plain Avro has no Variant representation; only visitors that explicitly support variants override this method.","triggerScenarios":"Visiting (e.g. via AvroSchemaUtil.convert or a custom AvroSchemaVisitor subclass that does not override variant()) an Avro record structured as an Iceberg Variant (metadata + value fields), typically in Avro files written for a v3 table containing variant columns.","commonSituations":"Reading Avro files containing Variant columns with a reader stack (reader function/visitor) built before Variant support; custom projection visitors that handle record/map/list/primitives but not variant; engine or library version too old for Variant types.","solutions":["Upgrade to an Iceberg version that supports the Variant type and its Avro mapping","Override variant() in your AvroSchemaVisitor subclass with the appropriate handling for metadata/value results","Exclude variant columns from the read projection if variants are not needed","If the engine lacks Variant support, cast/convert the column to a supported type at write time"],"exampleFix":"// before: visitor without variant support\nnew AvroSchemaVisitor<Type>() {\n  @Override public Type record(Schema rec, List<String> names, List<Type> types) { ... }\n  @Override public Type primitive(Schema p) { ... }\n}\n// after: override variant\nnew AvroSchemaVisitor<Type>() {\n  @Override public Type record(Schema rec, List<String> names, List<Type> types) { ... }\n  @Override public Type primitive(Schema p) { ... }\n  @Override public Type variant(Schema s, Type metadata, Type value) {\n    return Types.VariantType.get();\n  }\n}","handlingStrategy":"try-catch","validationCode":"boolean hasVariant = schema.columns().stream()\n    .anyMatch(f -> f.schema().type() instanceof Types.VariantType);\nif (hasVariant && !supportsVariant()) {\n  throw new IllegalStateException(\"Reader stack does not support Variant columns\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  return AvroSchemaUtil.convert(avroSchema, tableSchema.asStruct());\n} catch (UnsupportedOperationException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"variant\")) {\n    return convertWithoutVariantColumns(avroSchema, tableSchema);\n  }\n  throw e;\n}","preventionTips":["Keep Iceberg/engine versions aligned with the table format version in use (Variant requires v3 support)","Always override variant() in custom AvroSchemaVisitor subclasses when v3 tables are possible","Project away variant columns if the downstream reader cannot handle them","Convert variant columns to supported types for older consumers"],"tags":["avro","schema","variant","visitor"],"backgroundTag":"unsupported-operation","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}