{"record":{"id":"fcdbe4de4edf4a38","repo":"apache/beam","slug":"sample-size-must-be-0","errorCode":null,"errorMessage":"sample size must be >= 0","messagePattern":"sample size must be >= 0","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/Sample.java","lineNumber":306,"sourceCode":"    }\n  }\n\n  /**\n   * {@code CombineFn} that computes a fixed-size sample of a collection of values.\n   *\n   * @param <T> the type of the elements\n   */\n  public static class FixedSizedSampleFn<T>\n      extends CombineFn<\n          T, Top.BoundedHeap<KV<Integer, T>, SerializableComparator<KV<Integer, T>>>, Iterable<T>> {\n    private final int sampleSize;\n    private final Top.TopCombineFn<KV<Integer, T>, SerializableComparator<KV<Integer, T>>>\n        topCombineFn;\n    private final Random rand = new Random();\n\n    private FixedSizedSampleFn(int sampleSize) {\n      if (sampleSize < 0) {\n        throw new IllegalArgumentException(\"sample size must be >= 0\");\n      }\n\n      this.sampleSize = sampleSize;\n      topCombineFn = new Top.TopCombineFn<>(sampleSize, new KV.OrderByKey<>());\n    }\n\n    @Override\n    public Top.BoundedHeap<KV<Integer, T>, SerializableComparator<KV<Integer, T>>>\n        createAccumulator() {\n      return topCombineFn.createAccumulator();\n    }\n\n    @Override\n    public Top.BoundedHeap<KV<Integer, T>, SerializableComparator<KV<Integer, T>>> addInput(\n        Top.BoundedHeap<KV<Integer, T>, SerializableComparator<KV<Integer, T>>> accumulator,\n        T input) {\n      accumulator.addInput(KV.of(rand.nextInt(), input));\n      return accumulator;","sourceCodeStart":288,"sourceCodeEnd":324,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/Sample.java#L288-L324","documentation":"Sample.fixedSizeGlobally/sampleFn constructs FixedSizedSampleFn, which validates that the requested sample size is non-negative; a negative size is meaningless and throws IllegalArgumentException in the constructor. Zero is allowed (yields empty samples).","triggerScenarios":"Calling Sample.fixedSizeGlobally(n) or Sample.fixedSizePerKey(n) with n < 0, typically from a config value, subtraction, or user input not validated.","commonSituations":"Config values unset and later negated; computing sample size as a percentage of something that is negative; user-supplied CLI argument not validated.","solutions":["Validate sample size >= 0 before calling Sample.fixedSizeGlobally/PerKey","Clamp with Math.max(0, size)","Check the source of the size (config/user input) for negative defaults"],"exampleFix":"// before\nint n = getSampleSizeFromConfig(); // may be -1\nPCollection<T> sampled = input.apply(Sample.fixedSizeGlobally(n));\n// after\nint n = Math.max(0, getSampleSizeFromConfig());\nPCollection<T> sampled = input.apply(Sample.fixedSizeGlobally(n));","handlingStrategy":"validation","validationCode":"if (sampleSize < 0) { throw new IllegalArgumentException(\"sample size must be >= 0\"); }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Clamp sample sizes with Math.max(0, size) at the config boundary","Validate user/CLI-supplied sample sizes before building the pipeline","Prefer zero-sample (empty) semantics over negative defaults"],"tags":["java","apache-beam","pipeline-construction","argument-validation"],"backgroundTag":"invalid-argument-value","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}