What causes "incrementIndexSchema cannot be null" in apache/druid?

Call setIncrementalIndexSchema(new IncrementalIndexSchema.Builder()....build()) before build()

apache/druid · error · IllegalArgumentException

incrementIndexSchema cannot be null

Error message

incrementIndexSchema cannot be null

What it means

AppendableIndexBuilder.validate throws IllegalArgumentException when incrementalIndexSchema is null. Every appendable index needs a schema describing dimensions/metrics; without it the index cannot be constructed, so build() fails with this message ('incrementIndexSchema cannot be null').

Source

Thrown at processing/src/main/java/org/apache/druid/segment/incremental/AppendableIndexBuilder.java:112

  {
    this.maxBytesInMemory = maxBytesInMemory;
    return this;
  }

  public AppendableIndexBuilder setPreserveExistingMetrics(final boolean preserveExistingMetrics)
  {
    this.preserveExistingMetrics = preserveExistingMetrics;
    return this;
  }

  public void validate()
  {
    if (maxRowCount <= 0) {
      throw new IllegalArgumentException("Invalid max row count: " + maxRowCount);
    }

    if (incrementalIndexSchema == null) {
      throw new IllegalArgumentException("incrementIndexSchema cannot be null");
    }
  }

  public final IncrementalIndex build()
  {
    log.debug("Building appendable index.");
    validate();
    return buildInner();
  }

  protected abstract IncrementalIndex buildInner();
}

View on GitHub (pinned to 9b90983fd2)

Solutions

Call setIncrementalIndexSchema(new IncrementalIndexSchema.Builder()....build()) before build()
Ensure the schema-producing code path is not returning null; add an early null check
Use DimensionSchema-based schema builders to construct a valid schema

Example fix

// before
builder = new IncrementalIndex.Builder().maxRowCount(1000).build(); // no schema
// after
IncrementalIndexSchema schema = new IncrementalIndexSchema.Builder()
    .withDimensionsSpec(new DimensionsSpec(null))
    .withMetrics(...)
    .build();
builder.setIncrementalIndexSchema(schema).build();

Defensive patterns

Strategy: validation

Validate before calling

if (schema == null) { throw new IllegalArgumentException("incrementalIndexSchema must be set before build()"); }

Try / catch

try { builder.validate(); } catch (IllegalArgumentException e) { if (e.getMessage().contains("cannot be null")) { builder.setIncrementalIndexSchema(defaultSchema()); } else { throw e; } }

Prevention

Construct the schema immediately after creating the builder
Assert non-null schema in helper methods wrapping the builder
Centralize index construction in one utility with mandatory schema parameter

When it happens

Trigger: Building an IncrementalIndex with the builder without calling setIncrementalIndexSchema(...) (or the schema arg being null) before build().

Common situations: Programmatic index construction where schema setup was skipped or conditional code path skipped setIncrementalIndexSchema; null schema deserialized from config.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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