apache/druid · error · IllegalStateException

No serde for complexTypeName[%s]

Error message

No serde for complexTypeName[%s]

What it means

After confirming the column type is COMPLEX with a name, ComplexFieldReader.createFromType resolves the ComplexMetricSerde via ComplexMetrics.getSerdeForType(complexTypeName). It throws ISE when no serde is registered for that name, meaning the runtime cannot deserialize this complex column's values.

Source

Thrown at processing/src/main/java/org/apache/druid/frame/field/ComplexFieldReader.java:72

public class ComplexFieldReader implements FieldReader
{
  private final ComplexMetricSerde serde;

  ComplexFieldReader(final ComplexMetricSerde serde)
  {
    this.serde = Preconditions.checkNotNull(serde, "serde");
  }

  public static ComplexFieldReader createFromType(final ColumnType columnType)
  {
    if (columnType == null || columnType.getType() != ValueType.COMPLEX || columnType.getComplexTypeName() == null) {
      throw new ISE("Expected complex type with defined complexTypeName, but got [%s]", columnType);
    }

    final ComplexMetricSerde serde = ComplexMetrics.getSerdeForType(columnType.getComplexTypeName());

    if (serde == null) {
      throw new ISE("No serde for complexTypeName[%s]", columnType.getComplexTypeName());
    }

    return new ComplexFieldReader(serde);
  }

  @Override
  public ColumnValueSelector<?> makeColumnValueSelector(Memory memory, ReadableFieldPointer fieldPointer)
  {
    return new Selector<>(memory, fieldPointer, serde);
  }

  @Override
  public DimensionSelector makeDimensionSelector(
      Memory memory,
      ReadableFieldPointer fieldPointer,
      @Nullable ExtractionFn extractionFn
  )
  {

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Load the Druid extension that registers the missing serde (add it to the loadList in druid extensions config).
2. Verify ComplexMetrics.getSerdeForType(name) returns non-null for the reported type name in your runtime.
3. Check for typos or renames of the complex type name between write and read versions.
4. Ensure all data/coordinator/router nodes have the same extensions so any node can read the column.

Example fix

// before
// extensions=[] in runtime.properties, column complexTypeName=quantilesDoublesSketch
// after
// runtime.properties
druid.extensions.loadList=["druid-datasketches"]

if (ComplexMetrics.getSerdeForType(columnType.getComplexTypeName()) == null) { throw new IllegalStateException("extension providing serde for " + columnType.getComplexTypeName() + " not loaded"); }

try { reader = ComplexFieldReader.createFromType(t); } catch (IllegalStateException e) { log.error("missing serde: load the extension for {}", t.getComplexTypeName()); throw e; }

When it happens

Trigger: Reading a frame/segment whose complexTypeName (e.g. an aggregator-specific type like 'hyperUnique' or a custom sketch type) is not registered in ComplexMetrics — typically because the Druid extension providing the serde is not loaded.

Common situations: Querying segments written with an extension-enabled cluster from a node missing that extension; typos in complexTypeName; custom aggregators registered only on some services; version changes where a serde was renamed.

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

• Unable to handle complex type[%s]
• first argument must be a valid COMPLEX type name, got unknow
• extractValue without an aggregator factory is not supported.
• Unknown type:
• Expected complex type with defined complexTypeName, but got

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