{"record":{"id":"329a7964689654c8","repo":"apache/druid","slug":"maxretainedpartitionsketchbytes-must-be-positive","errorCode":null,"errorMessage":"maxRetainedPartitionSketchBytes must be positive","messagePattern":"maxRetainedPartitionSketchBytes must be positive","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"multi-stage-query/src/main/java/org/apache/druid/msq/kernel/controller/ControllerQueryKernelConfig.java","lineNumber":62,"sourceCode":"  private final String controllerHost;\n  @Nullable\n  private final List<String> workerIds;\n  private final Map<String, Object> workerContextMap;\n\n  ControllerQueryKernelConfig(\n      int maxRetainedPartitionSketchBytes,\n      int maxConcurrentStages,\n      boolean pipeline,\n      boolean durableStorage,\n      boolean faultTolerance,\n      MSQDestination destination,\n      @Nullable String controllerHost,\n      @Nullable List<String> workerIds,\n      Map<String, Object> workerContextMap\n  )\n  {\n    if (maxRetainedPartitionSketchBytes <= 0) {\n      throw new IAE(\"maxRetainedPartitionSketchBytes must be positive\");\n    }\n\n    if (pipeline && maxConcurrentStages < 2) {\n      throw new IAE(\"maxConcurrentStagesPerWorker must be >= 2 when pipelining\");\n    }\n\n    if (maxConcurrentStages <= 0) {\n      throw new IAE(\"maxConcurrentStagesPerWorker must be positive\");\n    }\n\n    if (pipeline && faultTolerance) {\n      throw new IAE(\"Cannot pipeline with fault tolerance\");\n    }\n\n    if (pipeline && durableStorage) {\n      throw new IAE(\"Cannot pipeline with durable storage\");\n    }\n","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/multi-stage-query/src/main/java/org/apache/druid/msq/kernel/controller/ControllerQueryKernelConfig.java#L44-L80","documentation":"ControllerQueryKernelConfig's constructor validates maxRetainedPartitionSketchBytes and throws IAE when it is <= 0. This setting bounds how many bytes of partition-boundary sketch data the controller retains per partition during shuffle; a non-positive value is meaningless and rejected eagerly at kernel construction.","triggerScenarios":"Building a ControllerQueryKernel (or the enclosing controller config) with maxRetainedPartitionSketchBytes set to 0 or a negative number, e.g. from a context key like maxRetainedPartitionSketchBytes bound to 0, an unset/empty numeric parsed as 0, or a negative value supplied in the query context.","commonSituations":"Users setting druid.msq.maxRetainedPartitionSketchBytes (or the query context equivalent) to 0 expecting 'unlimited', typos producing negative values, or programmatic config builders defaulting the int to 0 instead of the proper default (e.g. 1GB, 1073741824).","solutions":["Remove the override so the built-in default (1073741824, 1 GiB) applies.","Set maxRetainedPartitionSketchBytes in the query context to a positive integer, e.g. \"maxRetainedPartitionSketchBytes\": 1073741824.","If computed dynamically, clamp it: Math.max(1, computedValue) before constructing the config.","Check for string-to-int parsing of an empty/unset value yielding 0 in the caller that builds the config."],"exampleFix":"// before\ncontext.put(\"maxRetainedPartitionSketchBytes\", 0);\n\n// after\ncontext.put(\"maxRetainedPartitionSketchBytes\", 1073741824); // 1 GiB","handlingStrategy":"validation","validationCode":"final int sketchBytes = context.getInt(\"maxRetainedPartitionSketchBytes\");\nif (sketchBytes <= 0) {\n  throw new IllegalArgumentException(\"maxRetainedPartitionSketchBytes must be > 0, got \" + sketchBytes);\n}","typeGuard":null,"tryCatchPattern":"try {\n  kernelConfig = ControllerQueryKernelConfig.builder()...build();\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().contains(\"maxRetainedPartitionSketchBytes\")) {\n    // fall back to default 1073741824 and rebuild\n  }\n}","preventionTips":["Never set this key to 0 expecting 'unlimited'; omit it to use the default.","Validate user-supplied query context ints before submission.","Centralize MSQ context-key defaults in one helper."],"tags":["msq","configuration","validation","iae"],"backgroundTag":"invalid-config-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"}