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.

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)

Solutions

1. Check for mixed Iceberg jar versions on the classpath and align all iceberg-spark/iceberg-core artifacts to one version
2. Upgrade Iceberg — new dummy holder types are supported in newer releases
3. If you implement a custom VectorHolder, wrap your constant data in ConstantVectorHolder instead of a custom holder
4. 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);

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

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

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

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

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

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