apache/druid · error · IllegalArgumentException

partitionDimensions must be specified

Error message

partitionDimensions must be specified

What it means

Parallel (native batch) index tasks require that when a range partitioning strategy is used with dynamic partitioning disabled (DimensionRangePartitionsSpec), the list of partition dimensions must be explicitly provided. The tuning config validation throws IAE when a DimensionRangePartitionsSpec is present but its partitionDimensions field is null or empty, because range partitioning needs at least one dimension to compute ranges on.

Source

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

    this.maxNumSegmentsToMerge = maxNumSegmentsToMerge == null
                                 ? DEFAULT_MAX_NUM_SEGMENTS_TO_MERGE
                                 : maxNumSegmentsToMerge;

    this.totalNumMergeTasks = totalNumMergeTasks == null
                            ? DEFAULT_TOTAL_NUM_MERGE_TASKS
                            : totalNumMergeTasks;

    this.maxAllowedLockCount = maxAllowedLockCount == null
                               ? DEFAULT_MAX_ALLOWED_LOCK_COUNT
                               : maxAllowedLockCount;

    Preconditions.checkArgument(this.maxNumConcurrentSubTasks > 0, "maxNumConcurrentSubTasks must be positive");
    Preconditions.checkArgument(this.maxNumSegmentsToMerge > 0, "maxNumSegmentsToMerge must be positive");
    Preconditions.checkArgument(this.totalNumMergeTasks > 0, "totalNumMergeTasks must be positive");
    if (getPartitionsSpec() != null && getPartitionsSpec() instanceof DimensionRangePartitionsSpec) {
      List<String> partitionDimensions = ((DimensionRangePartitionsSpec) getPartitionsSpec()).getPartitionDimensions();
      if (partitionDimensions == null || partitionDimensions.isEmpty()) {
        throw new IAE("partitionDimensions must be specified");
      }
    }
  }

  @Nullable
  @JsonProperty
  public SplitHintSpec getSplitHintSpec()
  {
    return splitHintSpec;
  }

  @JsonProperty
  public int getMaxNumConcurrentSubTasks()
  {
    return maxNumConcurrentSubTasks;
  }

  @JsonProperty

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Add a non-empty partitionDimensions array to the 'partitionsSpec' in the tuning config (e.g. "partitionDimensions": ["dim1"]).
2. If you don't need range partitioning, switch partitionsSpec type to 'hashed' or 'dynamic', which don't require partitionDimensions.
3. Validate the spec JSON with Druid's ingestion spec validator / MSQ explainer before submitting.

Example fix

// before
"partitionsSpec": {
  "type": "range",
  "maxRowsPerSegment": 5000000
}
// after
"partitionsSpec": {
  "type": "range",
  "partitionDimensions": ["channel"],
  "maxRowsPerSegment": 5000000
}

// before submitting the tuning config
if ("range".equals(partitionsSpec.get("type"))
    && (partitionsSpec.get("partitionDimensions") == null
        || ((List<?>) partitionsSpec.get("partitionDimensions")).isEmpty())) {
  throw new IllegalArgumentException("range partitionsSpec requires non-empty partitionDimensions");
}

try { submitSpec(spec); } catch (IllegalArgumentException e) { if (e.getMessage().contains("partitionDimensions must be specified")) { /* fix spec: add partitionDimensions */ } else { throw e; } }

When it happens

Trigger: Submitting a ParallelIndexTuningConfig (e.g. via a batch ingestion spec) whose partitionsSpec has type 'range' but omits partitionDimensions, or sends an empty list for it.

Common situations: Users migrating from 'hashed' or 'dynamic' partitioning to 'range' partitioning and forgetting that range partitioning in Druid requires partitionDimensions; hand-edited JSON specs where the field was deleted; programmatically built specs that set only maxRowsPerSegment/targetRowsPerSegment.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• forceGuaranteedRollup is incompatible with partitionsSpec: %
• Root partition range[%d, %d] of new segments doesn't match t
• DimensionDistributionPhaseRunner has been stopped. %s
• Exception while writing distribution file for interval [%s],
• Error while reading distribution for interval [%s], task [%s

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