apache/iceberg · error · java.lang.IllegalStateException

Unknown dummy vector holder: ${holder}

Error message

Unknown dummy vector holder: ${holder}

What it means

During vectorized Spark reads, Iceberg builds result column vectors from 'dummy vector holders' used for constant/padding columns. ColumnVectorBuilder.build recognizes specific holder classes (constant holders, etc.); if a holder of an unexpected class is passed, it throws IllegalStateException because the builder cannot produce a valid column vector for it. This indicates an internal inconsistency in how the batch was constructed rather than bad user data.

Source

Thrown at spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/data/vectorized/ColumnVectorBuilder.java:39

import org.apache.iceberg.arrow.vectorized.VectorHolder;
import org.apache.iceberg.arrow.vectorized.VectorHolder.ConstantVectorHolder;
import org.apache.iceberg.types.Type;
import org.apache.iceberg.types.Types;
import org.apache.spark.sql.vectorized.ColumnVector;

class ColumnVectorBuilder {

  public ColumnVector build(VectorHolder holder, int numRows) {
    if (holder.isDummy()) {
      if (holder instanceof VectorHolder.DeletedVectorHolder) {
        return new DeletedColumnVector(Types.BooleanType.get());
      } else if (holder instanceof ConstantVectorHolder) {
        ConstantVectorHolder<?> constantHolder = (ConstantVectorHolder<?>) holder;
        Type icebergType = constantHolder.icebergType();
        Object value = constantHolder.getConstant();
        return new ConstantColumnVector(icebergType, numRows, value);
      } else {
        throw new IllegalStateException("Unknown dummy vector holder: " + holder);
      }
    } else {
      return new IcebergArrowColumnVector(holder);
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Check the classpath for duplicate/mismatched iceberg-spark jars and align all Iceberg artifacts to one version
2. Disable vectorized reads as a workaround: set spark.sql.iceberg.vectorization.enabled=false
3. Upgrade Iceberg so the holder type and ColumnVectorBuilder are from the same compatible release
4. If a custom holder was added, extend ColumnVectorBuilder.build to handle it

Example fix

// before: spark-sql default with mixed iceberg jars
spark.sql(...)
// after: disable vectorization to isolate/avoid
spark.conf.set("spark.sql.iceberg.vectorization.enabled", "false")

// Ensure a single consistent Iceberg version on the classpath
// ./gradlew dependencies | grep iceberg  — no duplicate/mixed iceberg-spark versions

try {
  spark.read.format("iceberg").load("db.table").collect();
} catch (IllegalStateException e) {
  if (e.getMessage().startsWith("Unknown dummy vector holder:")) {
    spark.conf.set("spark.sql.iceberg.vectorization.enabled", "false"); // fallback
  } else throw e;
}

When it happens

Trigger: A vectorized read (spark.sql.iceberg.vectorization.enabled=true) where readDataToColumnVectors encounters a VectorHolder that is neither an IcebergArrowColumnVector-backed holder nor any of the recognized dummy holder types (constant, deleted-row, etc.) — i.e., a new dummy holder type added without updating the builder.

Common situations: Mixed Iceberg runtime versions on the classpath (a holder class from a newer/older jar); custom vectorized-read patches; a metadata column or constant-folded expression producing a holder the builder doesn't know.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Unknown dummy vector holder: ${holder}
• ${this.getClass()} does not implement getArray
• ${this.getClass()} does not implement getMap
• Unsupported type - byte
• Unknown dummy vector holder:

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