apache/druid · error · IllegalStateException

DimensionSpec[ ] cannot be vectorized

Error message

DimensionSpec[%s] cannot be vectorized

What it means

Druid's vectorized query engine requires every DimensionSpec to declare vectorization compatibility via canVectorize(). When a query asks for a multi-value dimension vector selector and the spec cannot be vectorized, the selector factory throws this IllegalStateException rather than silently falling back. It is an engine-internal consistency check.

Solutions

1. Use a vectorization-compatible DimensionSpec (e.g. DefaultDimensionSpec) for the column
2. Disable vectorization for the query (set query context 'vectorize':'false') to force the non-vectorized path
3. Fix or update the custom DimensionSpec implementation to correctly implement canVectorize()

Example fix

// before
DimensionSpec spec = new MyCustomDimensionSpec("col", "out"); // canVectorize() == false
// after
DimensionSpec spec = new DefaultDimensionSpec("col", "out"); // vectorizable

if (!dimensionSpec.canVectorize()) { spec = new DefaultDimensionSpec(col, out); } // or set vectorize=false in context

boolean usable = spec != null && spec.canVectorize();

try { sel = factory.makeMultiValueDimensionSelector(spec); } catch (IllegalStateException e) { /* fall back to non-vectorized query */ }

When it happens

Trigger: Querying with a DimensionSpec (e.g. certain extraction-fn or expression specs) that reports canVectorize()==false while the query is planned in vectorized mode and requests makeMultiValueDimensionSelector.

Common situations: Using an extraction dimension spec or custom extension DimensionSpec in an aggregator that supports vectorization; extension code adding a non-vectorizable DimensionSpec to a vector-enabled query.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• DimensionSpec[ ] cannot vectorize
• A batch appenderator was already created for this peon's…
• A realtime appenderator was already created for this peon's…
• Aggregator[ ] cannot vectorize
• Already started.

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/f5cbb06c9fe21779. Report an issue: GitHub.

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/segment/vector/QueryableIndexVectorColumnSelectorFactory.java:82

    this.virtualColumns = virtualColumns;
    this.columnSelector = columnSelector;
    this.singleValueDimensionSelectorCache = new HashMap<>();
    this.multiValueDimensionSelectorCache = new HashMap<>();
    this.valueSelectorCache = new HashMap<>();
    this.objectSelectorCache = new HashMap<>();
  }

  @Override
  public ReadableVectorInspector getReadableVectorInspector()
  {
    return offset;
  }

  @Override
  public MultiValueDimensionVectorSelector makeMultiValueDimensionSelector(final DimensionSpec dimensionSpec)
  {
    if (!dimensionSpec.canVectorize()) {
      throw new ISE("DimensionSpec[%s] cannot be vectorized", dimensionSpec);
    }
    Function<DimensionSpec, MultiValueDimensionVectorSelector> mappingFunction = spec -> {
      if (virtualColumns.exists(spec.getDimension())) {
        return virtualColumns.makeMultiValueDimensionVectorSelector(dimensionSpec, this, columnSelector, offset);
      }

      final ColumnHolder holder = columnSelector.getColumnHolder(spec.getDimension());
      if (holder == null
          || holder.getCapabilities().isDictionaryEncoded().isFalse()
          || !holder.getCapabilities().is(ValueType.STRING)
          || holder.getCapabilities().hasMultipleValues().isFalse()) {
        throw new ISE(
            "Column[%s] is not a multi-value string column, do not ask for a multi-value selector",
            spec.getDimension()
        );
      }

      @SuppressWarnings("unchecked")

View on GitHub (pinned to 9b90983fd2)