apache/iceberg · error · IllegalStateException

Unknown dummy vector holder: ${holder}

Error message

Unknown dummy vector holder: ${holder}

What it means

ColumnVectorBuilder.build() materializes a real Spark ColumnVector from a registered dummy vector holder. It recognizes specific holder implementations (constant, null, etc.); if the holder type is none of the known kinds, it throws IllegalStateException because the builder cannot know how to create a vector for it. This indicates an internal inconsistency: an unsupported or unexpected DummyVectorHolder was passed into the vectorized read path.

Source

Thrown at spark/v4.2/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 the runtime class of the holder being passed (print holder.getClass()) and confirm it is one of the supported DummyVectorHolder implementations.
2. Add a matching instanceof branch in ColumnVectorBuilder.build() that constructs the appropriate ColumnVector for the new holder type.
3. If the holder should have been a known type, trace where it was created and fix the creation site to use a supported holder.
4. Upgrade to an Iceberg version where the holder type you need is supported in the vectorized read path.

Example fix

// before
} else {
  throw new IllegalStateException("Unknown dummy vector holder: " + holder);
}
// after
} else if (holder instanceof MyNewVectorHolder) {
  MyNewVectorHolder h = (MyNewVectorHolder) holder;
  return new MyNewColumnVector(h.icebergType(), numRows, h.getValue());
} else {
  throw new IllegalStateException("Unknown dummy vector holder: " + holder);
}

if (!(holder instanceof ConstantVectorHolder<?> || holder instanceof NullVectorHolder)) {
  throw new IllegalArgumentException("Unsupported dummy vector holder: " + holder.getClass());
}

static boolean isSupportedHolder(DummyVectorHolder<?> h) {
  return h instanceof ConstantVectorHolder<?> || h instanceof NullVectorHolder;
}

When it happens

Trigger: Calling build() with a holder that is neither a known nor an instanceof a recognized DummyVectorHolder subclass (e.g. a new holder type added without extending build()'s dispatch, or a custom holder passed via readDataToColumnVectors).

Common situations: Developers adding a new DummyVectorHolder variant for a new Iceberg feature but forgetting to add the matching branch in ColumnVectorBuilder; upgrading Iceberg/Spark versions where holder classes changed; custom patches that introduce new holder types.

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/eb44df5437a4d5ae. Report an issue: GitHub.