apache/druid · error · IllegalStateException

Don't know how to handle type

Error message

Don't know how to handle type[%s]

What it means

IncrementalIndex.makeColumnValueSelector throws IllegalStateException when an aggregator's intermediate complex type has no registered ComplexMetricSerde (ComplexMetrics.getSerdeForType returned null). Complex metrics (e.g. hyperUnique, sketches) require a serde registered in ComplexMetrics; an unregistered type means Druid cannot extract values for that aggregator.

Solutions

  1. Load the extension providing the serde (add it to druid.extensions.loadList)
  2. Verify ComplexMetrics.getSerdeForType(name) returns non-null before building the index/query
  3. Register the serde manually in tests: ComplexMetrics.registerSerde(name, serde)

Example fix

// before
// extension 'druid-datasketches' not loaded; serde for "quantilesDoublesSketch" is null
// after
// in runtime.properties: druid.extensions.loadList=["druid-datasketches"]
// or in test setup:
ComplexMetrics.registerSerde("quantilesDoublesSketch", new QuantilesDoublesSketchSerde());
Defensive patterns

Strategy: validation

Validate before calling

String t = agg.getIntermediateType().getComplexTypeName(); if (ComplexMetrics.getSerdeForType(t) == null) { throw new IllegalStateException("Complex metric serde not registered for " + t + "; load the providing extension"); }

Try / catch

try { selector = index.makeColumnValueSelector(...); } catch (IllegalStateException e) { if (e.getMessage().startsWith("Don't know how to handle type")) { throw new QueryUnsupportedException("missing extension for complex metric", e); } throw e; }

Prevention

When it happens

Trigger: Querying an IncrementalIndex with a complex aggregator whose intermediateType complex name (e.g. 'hyperUnique', 'quantilesDoublesSketch') was never registered via ComplexMetrics.registerSerde, typically because the extension providing the serde is not loaded.

Common situations: Missing druid-(hyperUnique/datasketches) extension in the runtime classpath; query referencing a metric type from an extension not loaded on the node; custom aggregator whose serde was never registered in unit tests.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/segment/incremental/IncrementalIndex.java:157

    );

    class IncrementalIndexInputRowColumnSelectorFactory implements ColumnSelectorFactory
    {
      @Override
      public ColumnValueSelector<?> makeColumnValueSelector(final String column)
      {
        final ColumnValueSelector selector = baseSelectorFactory.makeColumnValueSelector(column);

        if (agg == null || !agg.getIntermediateType().is(ValueType.COMPLEX)) {
          return selector;
        } else {
          // Wrap selector in a special one that uses ComplexMetricSerde to modify incoming objects.
          // For complex aggregators that read from multiple columns, we wrap all of them. This is not ideal but it
          // has worked so far.
          final String complexTypeName = agg.getIntermediateType().getComplexTypeName();
          final ComplexMetricSerde serde = ComplexMetrics.getSerdeForType(complexTypeName);
          if (serde == null) {
            throw new ISE("Don't know how to handle type[%s]", complexTypeName);
          }

          final ComplexMetricExtractor extractor = serde.getExtractor();
          return new ColumnValueSelector()
          {
            @Override
            public boolean isNull()
            {
              return selector.isNull();
            }

            @Override
            public long getLong()
            {
              return selector.getLong();
            }

            @Override

View on GitHub (pinned to 9b90983fd2)