apache/druid · error · IllegalStateException

forceGuaranteedRollup is incompatible with partitionsSpec: %

Error message

forceGuaranteedRollup is incompatible with partitionsSpec: %s

What it means

Thrown by checkPartitionsSpecForForceGuaranteedRollup when forceGuaranteedRollup (perfect rollup) is enabled but the configured partitionsSpec does not support it, per partitionsSpec.isForceGuaranteedRollupCompatible(). Only hash and single-dim/range partitioning with fixed shard counts are compatible with guaranteed rollup.

Source

Thrown at indexing-service/src/main/java/org/apache/druid/indexing/common/task/batch/parallel/ParallelIndexSupervisorTask.java:285

                                           && ingestionSchema.getDataSchema()
                                                             .getGranularitySpec()
                                                             .inputIntervals()
                                                             .isEmpty();
    if (missingIntervalsInOverwriteMode) {
      addToContext(Tasks.FORCE_TIME_CHUNK_LOCK_KEY, true);
    }

    awaitSegmentAvailabilityTimeoutMillis = ingestionSchema.getTuningConfig().getAwaitSegmentAvailabilityTimeoutMillis();
    this.ingestionState = IngestionState.NOT_STARTED;
    this.isCompactionTask = isCompactionTask;
  }

  private static void checkPartitionsSpecForForceGuaranteedRollup(PartitionsSpec partitionsSpec)
  {
    if (!partitionsSpec.isForceGuaranteedRollupCompatible()) {
      String incompatibiltyMsg = partitionsSpec.getForceGuaranteedRollupIncompatiblityReason();
      String msg = "forceGuaranteedRollup is incompatible with partitionsSpec: " + incompatibiltyMsg;
      throw new ISE(msg);
    }
  }

  @Override
  public String getType()
  {
    return TYPE;
  }

  @Nonnull
  @JsonIgnore
  @Override
  public Set<ResourceAction> getInputSourceResources()
  {
    return getIngestionSchema().getIOConfig().getInputSource() != null ?
           getIngestionSchema().getIOConfig().getInputSource().getTypes()
                               .stream()
                               .map(AuthorizationUtils::createExternalResourceReadAction)

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Replace dynamic partitionsSpec with a hash or range (single_dim) partitionsSpec including numShards (or maxNumPartitions for hash).
2. Set forceGuaranteedRollup=false to accept best-effort (append-compatible) rollup if perfect rollup is not required.
3. Pre-compute numShards (or use maxNumPartitions with hash partitioning) so partition counts are fixed.

Example fix

// before
"partitionsSpec": { "type": "dynamic", "maxTotalRows": 5000000 }, "forceGuaranteedRollup": true
// after
"partitionsSpec": { "type": "hash", "numShards": 4 }, "forceGuaranteedRollup": true

if (tuningConfig.isForceGuaranteedRollup()
    && !(partitionsSpec instanceof HashedPartitionsSpec || "single_dim".equals(partitionsSpec.getType()))) {
  throw new IllegalArgumentException("forceGuaranteedRollup requires hash or single_dim partitionsSpec with fixed numShards");
}

When it happens

Trigger: Setting forceGuaranteedRollup=true with a dynamic partitionsSpec (dynamic partitioning cannot guarantee perfect rollup), or a hash/dim partitionsSpec missing numShards/maxNumPartitions settings required for deterministic partitioning.

Common situations: Migrating task configs from append-mode batch to perfect-rollup batch without changing 'partitionsSpec' from dynamic; copying tuning configs between tasks; auto-generated specs defaulting to dynamic partitioning.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• forceGuaranteedRollup is set but partitionsSpec [%s] is not
• Root partition range[%d, %d] of new segments doesn't match t
• Number of locks exceeded maxAllowedLockCount [%s].
• Unknown tuningConfig type: [%s], Must be in [%s, %s, %s]
• Estimated numShards [%s] exceeds integer bounds.

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