apache/iceberg · error · UnsupportedOperationException

Vectorized reads are not supported yet for struct fields

Error message

Vectorized reads are not supported yet for struct fields

What it means

VectorizedReaderBuilder.struct rejects vectorized reading of nested struct fields whenever an expected StructType is present. Vectorization is only implemented for top-level primitive columns, so a nested struct column with a known expected type is unsupported and the builder throws UnsupportedOperationException (returns null only for unexpected/group-only structs).

Solutions

1. Disable vectorized reads for the table (spark.read.option vectorized-reader-enabled=false or table property) so generic readers handle structs
2. Project only primitive columns in vectorized queries
3. Upgrade Iceberg — newer versions may add nested-type vectorization

Example fix

// before
spark.read.option("vectorized-reader-enabled", "true").load("table") // selects struct col
// after
spark.read.option("vectorized-reader-enabled", "false").load("table")

boolean hasStruct = expectedSchema.columns().stream()
    .anyMatch(f -> f.type().typeId() == Type.TypeID.STRUCT);
if (hasStruct) {
  // disable vectorization: spark.read.option("vectorized-reader-enabled", "false")
}

boolean vectorizable(Schema s) {
  return s.columns().stream().noneMatch(f -> f.type().typeId() == Type.TypeID.STRUCT);
}

try {
  reader = vectorizedBuilder.build();
} catch (UnsupportedOperationException e) {
  if (e.getMessage().contains("struct fields")) { reader = genericBuilder.build(); }
  else throw e;
}

When it happens

Trigger: Enabling vectorized reads on a table whose projection includes a struct-typed column — IcebergParquetReaders.buildReader hits the struct visit with a non-null expected StructType.

Common situations: Queries selecting nested struct columns with vectorization enabled (default on); upgrading tables to include complex types while relying on the vectorized path.

Related errors

• Struct type is not supported
• Byte stream split encoding is not supported for type " +…
• Cannot convert nested accessor to position
• Child columns is null hence cannot find index:
• does not implement getArray

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

Appendix: source

Thrown at arrow/src/main/java/org/apache/iceberg/arrow/vectorized/VectorizedReaderBuilder.java:152

      return VectorizedArrowReader.nulls();
    }

    throw new IllegalArgumentException(String.format("Missing required field: %s", field.name()));
  }

  private <T> ConstantVectorReader<T> constantReader(Types.NestedField field, T constant) {
    return new ConstantVectorReader<>(field, constant);
  }

  protected VectorizedReader<?> vectorizedReader(List<VectorizedReader<?>> reorderedFields) {
    return readerFactory.apply(reorderedFields);
  }

  @Override
  public VectorizedReader<?> struct(
      Types.StructType expected, GroupType groupType, List<VectorizedReader<?>> fieldReaders) {
    if (expected != null) {
      throw new UnsupportedOperationException(
          "Vectorized reads are not supported yet for struct fields");
    }
    return null;
  }

  @Override
  public ParquetVariantVisitor<VectorizedReader<?>> variantVisitor() {
    return new VectorizedVariantVisitor(
        currentPath(), parquetSchema, icebergSchema, rootAllocator, setArrowValidityVector);
  }

  @Override
  public VectorizedReader<?> variant(
      Types.VariantType iVariant, GroupType variant, VectorizedReader<?> result) {
    return result;
  }

  @Override

View on GitHub (pinned to 86d9c8fc54)