{"record":{"id":"f19c5b9aec0fad04","repo":"apache/druid","slug":"bucketsize-must-be-a-power-of-two-but-was-d","errorCode":null,"errorMessage":"bucketSize must be a power of two but was[%,d]","messagePattern":"bucketSize must be a power of two but was\\[%,d\\]","errorType":"validation","errorClass":"ISE","httpStatus":null,"severity":"error","filePath":"processing/src/main/java/org/apache/druid/segment/column/StringEncodingStrategy.java","lineNumber":105,"sourceCode":"\n  class FrontCoded implements StringEncodingStrategy\n  {\n\n    @JsonProperty\n    private final int bucketSize;\n\n    @JsonProperty\n    private final byte formatVersion;\n\n    @JsonCreator\n    public FrontCoded(\n        @JsonProperty(\"bucketSize\") @Nullable Integer bucketSize,\n        @JsonProperty(\"formatVersion\") @Nullable Byte version\n    )\n    {\n      this.bucketSize = bucketSize == null ? FrontCodedIndexed.DEFAULT_BUCKET_SIZE : bucketSize;\n      if (Integer.bitCount(this.bucketSize) != 1) {\n        throw new ISE(\"bucketSize must be a power of two but was[%,d]\", bucketSize);\n      }\n      this.formatVersion = version == null\n                           ? FrontCodedIndexed.DEFAULT_VERSION\n                           : FrontCodedIndexed.validateVersion(version);\n    }\n\n    public FrontCoded(@Nullable Integer bucketSize)\n    {\n      this(bucketSize, null);\n    }\n\n    @JsonProperty\n    public int getBucketSize()\n    {\n      return bucketSize;\n    }\n\n    @JsonProperty","sourceCodeStart":87,"sourceCodeEnd":123,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/processing/src/main/java/org/apache/druid/segment/column/StringEncodingStrategy.java#L87-L123","documentation":"The FrontCoded string encoding strategy requires its bucketSize to be a power of two (FrontCodedIndexed constraint for efficient bucket indexing). The constructor throws this ISE when a configured bucketSize has more than one bit set, e.g. 3, 12, 100.","triggerScenarios":"Deserializing or constructing a FrontCoded StringEncodingStrategy with @JsonProperty bucketSize set to a non-power-of-two integer (e.g. 3, 6, 24) from a column format spec / segment metadata JSON.","commonSituations":"Hand-edited ingestion/compaction specs choosing an arbitrary bucket size like 10; copying a spec where someone changed bucketSize from 16 to 20; a custom config generator that doesn't validate the constraint.","solutions":["Set bucketSize to a power of two (2, 4, 8, 16, 32, ...) — FrontCodedIndexed.DEFAULT_BUCKET_SIZE is 16 if omitted","Validate user-supplied bucketSize values before writing them into the column format spec","Remove the bucketSize property entirely to fall back to the default valid value"],"exampleFix":"// before\n\"stringDictionaryEncoding\": { \"type\": \"front-coded\", \"bucketSize\": 10 } // ISE: not a power of two\n// after\n\"stringDictionaryEncoding\": { \"type\": \"front-coded\", \"bucketSize\": 16 } // 16 = 2^4","handlingStrategy":"validation","validationCode":"if (bucketSize != null && Integer.bitCount(bucketSize) != 1) {\n  throw new IllegalArgumentException(\"bucketSize must be a power of two, got \" + bucketSize);\n}","typeGuard":"boolean isValidBucketSize(Integer bucketSize) {\n  return bucketSize == null || (bucketSize > 0 && Integer.bitCount(bucketSize) == 1);\n}","tryCatchPattern":"try {\n  FrontCoded fc = new FrontCoded(\"front-coded\", bucketSize, version);\n} catch (ISE e) {\n  LOG.warn(e, \"Invalid bucketSize, using default\");\n  fc = new FrontCoded(\"front-coded\", null, version); // defaults to 16\n}","preventionTips":["Validate JSON config fields (powers of two, ranges) before writing specs","Use named constants or omit bucketSize to get DEFAULT_BUCKET_SIZE","Add a schema/JSON-schema check for column format specs in tooling"],"tags":["java","front-coded","bucket-size","validation"],"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-17T20:17:13.540Z"}