{"record":{"id":"b212382b989452d1","repo":"apache/druid","slug":"cannot-bucket-with-s-partitioning","errorCode":null,"errorMessage":"Cannot bucket with %s partitioning","messagePattern":"Cannot bucket with (.+?) partitioning","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"multi-stage-query/src/main/java/org/apache/druid/msq/kernel/GlobalSortMaxCountShuffleSpec.java","lineNumber":78,"sourceCode":"    this.aggregate = aggregate;\n    this.limitHint = limitHint == null ? UNLIMITED : limitHint;\n    this.adjustable = adjustable;\n\n    if (maxPartitions < 1) {\n      throw new IAE(\"Partition count must be at least 1\");\n    }\n\n    if (adjustable && maxPartitions != 1) {\n      throw new IAE(\"Partition count must be 1 when adjustable is true, but was [%d]\", maxPartitions);\n    }\n\n    if (!clusterBy.sortable()) {\n      throw new IAE(\"ClusterBy key must be sortable\");\n    }\n\n    if (clusterBy.getBucketByCount() > 0) {\n      // Only GlobalSortTargetSizeShuffleSpec supports bucket-by.\n      throw new IAE(\"Cannot bucket with %s partitioning\", TYPE);\n    }\n  }\n\n  public GlobalSortMaxCountShuffleSpec(\n      final ClusterBy clusterBy,\n      final int maxPartitions,\n      final boolean aggregate,\n      final Long limitHint\n  )\n  {\n    this(clusterBy, maxPartitions, aggregate, limitHint, false);\n  }\n\n  @Override\n  public ShuffleKind kind()\n  {\n    return ShuffleKind.GLOBAL_SORT;\n  }","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/multi-stage-query/src/main/java/org/apache/druid/msq/kernel/GlobalSortMaxCountShuffleSpec.java#L60-L96","documentation":"GlobalSortMaxCountShuffleSpec only supports shuffle specs whose ClusterBy has no bucket-by keys; bucket-by partitioning is reserved exclusively for GlobalSortTargetSizeShuffleSpec. When a ClusterBy with bucketBy count > 0 is used to construct this shuffle spec (during ShuffleSpecFactory.create), the constructor throws IAE because it cannot represent bucketed partitioning.","triggerScenarios":"Building a shuffle spec via ShuffleSpecFactory.create with kind=MAX_COUNT and a ClusterBy whose getBucketByCount() > 0 (i.e. the query specifies bucket-by columns for a global-sort max-count shuffle).","commonSituations":"MSQ queries that specify a partitioning/DISTRIBUTED OVER bucket columns while using the max-count global sort shuffle; misconfigured query context choosing maxCount partitioning together with time-bucketed clustering.","solutions":["Remove bucket-by keys from the ClusterBy (drop the bucket columns in the query's clustering/partitioning spec)","Use GlobalSortTargetSizeShuffleSpec (TARGET_SIZE shuffle kind) if bucket-by partitioning is required","Adjust the query context/partitioning parameters so maxCount shuffle is not combined with bucket-by"],"exampleFix":"// before: bucket-by columns with MAX_COUNT shuffle\nnew GlobalSortMaxCountShuffleSpec(clusterByWithBucketBy, maxPartitions);\n// after: either strip bucket keys\nClusterBy sortableClusterBy = clusterBy.withoutBucketBy();\nnew GlobalSortMaxCountShuffleSpec(sortableClusterBy, maxPartitions);\n// or use TARGET_SIZE shuffle which supports bucket-by","handlingStrategy":"validation","validationCode":"if (clusterBy.getBucketByCount() > 0) {\n  throw new IllegalArgumentException(\"Use GlobalSortTargetSizeShuffleSpec (TARGET_SIZE) for bucket-by partitioning\");\n}\nnew GlobalSortMaxCountShuffleSpec(clusterBy, maxPartitions);","typeGuard":"static boolean supportsMaxCount(ClusterBy clusterBy) {\n  return clusterBy != null && clusterBy.getBucketByCount() == 0;\n}","tryCatchPattern":"try {\n  spec = new GlobalSortMaxCountShuffleSpec(clusterBy, maxPartitions);\n} catch (IllegalArgumentException e) {\n  spec = new GlobalSortTargetSizeShuffleSpec(clusterBy, targetSize, false);\n}","preventionTips":["Check clusterBy.getBucketByCount() before choosing the shuffle kind","Reserve MAX_COUNT shuffle for bucket-free clustering","Keep bucket-by queries on TARGET_SIZE partitioning"],"tags":["msq","shuffle-spec","invalid-argument","bucket-by"],"backgroundTag":"invalid-argument-value","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}