apache/iceberg · error · IllegalStateException

Unknown dummy vector holder: ${holder}

Error message

Unknown dummy vector holder: ${holder}

What it means

ColumnVectorBuilder.build converts dummy vector holders used during vectorized reads (NULL, constant) into Spark ColumnVectors. If a holder is neither a NullVectorHolder-like case nor a ConstantVectorHolder, the builder cannot classify it and throws IllegalStateException.

Source

Thrown at spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/data/vectorized/ColumnVectorBuilder.java:41

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 instanceof VectorHolder.VariantVectorHolder) {
      return new VariantColumnVector((VectorHolder.VariantVectorHolder) holder);
    } else 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. Ensure all iceberg-spark jars in the classpath are the same version (no mixed-version shading).
2. Report/log the holder class name — it identifies which code path created the unknown holder.
3. Work around by disabling vectorized reads for the affected scan if a hotfix is unavailable.

try {
  vectors = readDataToColumnVectors(task, expectedTypes, batch); 
} catch (IllegalStateException e) {
  if (e.getMessage().startsWith("Unknown dummy vector holder")) {
    // fall back to non-vectorized read path
    spark.conf().set("read.spark.vectorization.enabled", "false");
  }
}

When it happens

Trigger: readDataToColumnVectors passes a VectorHolder that is a dummy type not recognized by build (a new dummy holder kind introduced elsewhere but not handled here), i.e. an internal invariant violation in the vectorized read path.

Common situations: Almost always an Iceberg-internal bug or a mixed-version deployment where a newer component produces a holder type an older 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
• ${class} does not implement getArray

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