apache/druid · error · IllegalArgumentException

forceGuaranteedRollup is incompatible with partitionsSpec: %

Error message

forceGuaranteedRollup is incompatible with partitionsSpec: %s

What it means

PerfectRollupWorkerTask requires forceGuaranteedRollup (perfect rollup), which is only compatible with partitioning strategies that produce a fixed, complete partition layout. checkPartitionsSpec() throws IllegalArgumentException when the supplied PartitionsSpec reports itself incompatible, including the spec's own incompatibility reason in the message.

Source

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

    Preconditions.checkArgument(
        tuningConfig.isForceGuaranteedRollup(),
        "forceGuaranteedRollup must be set"
    );

    checkPartitionsSpec(tuningConfig.getGivenOrDefaultPartitionsSpec());

    this.granularitySpec = dataSchema.getGranularitySpec();
    this.dataSchema = dataSchema;
    this.tuningConfig = tuningConfig;
  }

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

  @Override
  public final boolean requireLockExistingSegments()
  {
    return true;
  }

  @Override
  public final List<DataSegment> findSegmentsToLock(TaskActionClient taskActionClient, List<Interval> intervals)
  {
    throw new UnsupportedOperationException("This task locks by timeChunk instead of segment");
  }

  @Override
  public final boolean isPerfectRollup()
  {

View on GitHub (pinned to 9b90983fd2)

Solutions

Set partitionsSpec to a rollup-compatible type (e.g. single-dim/partitioned 'hashed' with numShards or 'range' with resolved boundaries) as required for perfect rollup.
Disable forceGuaranteedRollup if you don't actually need perfect rollup and use the appropriate worker task.
Read the incompatibility reason embedded in the message to see exactly which property of the spec conflicts.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

// before creating the task
if (forceGuaranteedRollup && !partitionsSpec.isForceGuaranteedRollupCompatible()) {
  throw new IllegalArgumentException(
    "forceGuaranteedRollup incompatible: " + partitionsSpec.getForceGuaranteedRollupIncompatiblityReason());
}

Try / catch

try { new PerfectRollupWorkerTask(...); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("forceGuaranteedRollup is incompatible")) { /* switch partitionsSpec to hashed/range with fixed layout */ } else { throw e; } }

Prevention

When forceGuaranteedRollup=true, always use a fixed partition layout (hashed numShards or range with boundaries).
Don't copy tuning configs from dynamic-partitioned jobs into perfect-rollup jobs.
Read the spec's own incompatibility reason in the error message.

When it happens

Trigger: Creating a PerfectRollupWorkerTask (used by perfect-rollup compaction/ingestion) with a partitionsSpec such as dynamic or hashed dimension-based partitioning that cannot guarantee perfect rollup.

Common situations: Using a compaction/ingestion config with forceGuaranteedRollup=true but leaving a dynamic partitionsSpec; copying tuning configs from a non-rollup job; Druid version changes where a partitionsSpec's rollup compatibility changed.

Related errors

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