What causes "Unknown dummy vector holder: " in apache/iceberg?

Check for mixed Iceberg jar versions on the classpath and align all iceberg-spark/iceberg-core artifacts to one version

apache/iceberg · error · IllegalStateException

Unknown dummy vector holder:

Error message

Unknown dummy vector holder:

What it means

ColumnVectorBuilder.build() converts 'dummy' vector holders used during vectorized reads into real column vectors. If a holder is neither a constant holder nor one of the recognized dummy holder types, the builder cannot interpret it and throws IllegalStateException, indicating an internal invariant violation rather than user error.

Solutions

Check for mixed Iceberg jar versions on the classpath and align all iceberg-spark/iceberg-core artifacts to one version
Upgrade Iceberg — new dummy holder types are supported in newer releases
If you implement a custom VectorHolder, wrap your constant data in ConstantVectorHolder instead of a custom holder
File/inspect an Iceberg issue: this path should never be hit with stock readers

Example fix

// before
VectorHolder holder = myCustomHolder; // unknown dummy holder
// after
VectorHolder holder = new ConstantVectorHolder<>(numRows, icebergType, constantValue);

Defensive patterns

Strategy: try-catch

Validate before calling

if (!(holder instanceof ConstantVectorHolder) && !(isKnownDummyHolder(holder))) { throw new IllegalArgumentException("unsupported holder: " + holder.getClass()); }

Type guard

boolean isKnownHolder(VectorHolder h) { return h instanceof ConstantVectorHolder<?> || h.getClass().getName().startsWith("org.apache.iceberg.spark.data.vectorized"); }

Try / catch

try { vector = builder.build(holder, numRows); } catch (IllegalStateException e) { log.error("unknown holder {}", holder.getClass(), e); throw new IOException("unsupported vector holder", e); }

Prevention

Pin all Iceberg modules to one version
Use ConstantVectorHolder for constant data
Add a unit test for any custom VectorHolder implementation

When it happens

Trigger: A vectorized batch read (readDataToColumnVectors) encounters a VectorHolder that is not an instance of the supported dummy holder types (e.g. ConstantVectorHolder) and not a plain vector holder either — typically after a custom or newly added holder implementation is passed into the builder.

Common situations: Appears when Iceberg's vectorized read path introduces a new holder type without updating the builder, when a Spark/Paimon-style wrapper holder leaks into Iceberg's reader, or when internal refactors pair mismatched reader/builder versions (mixed jar versions of iceberg-spark on the classpath).

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

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

Appendix: source

Thrown at spark/v4.0/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)