apache/beam · error · IllegalArgumentException

The relative error must be positive

Error message

The relative error must be positive

What it means

SketchFrequencies.CountMinSketchFn.withAccuracy validates the requested relative error epsilon; it must be strictly positive because a zero or negative error is meaningless for a Count-Min Sketch (the width of the sketch is derived as ceil(2/epsilon)). An epsilon <= 0 throws this IllegalArgumentException immediately at pipeline construction time.

Source

Thrown at sdks/java/extensions/sketching/src/main/java/org/apache/beam/sdk/extensions/sketching/SketchFrequencies.java:383

        throw new IllegalArgumentException(
            "Coder must be deterministic to perform this sketch." + e.getMessage(), e);
      }
      return new CountMinSketchFn<>(coder, 0.01, 0.999);
    }

    /**
     * Returns a new {@link CountMinSketchFn} combiner with new precision accuracy parameters {@code
     * epsilon} and {@code confidence}.
     *
     * <p>Keep in mind that the lower the {@code epsilon} value, the greater the width, and the
     * greater the confidence, the greater the depth.
     *
     * @param epsilon the error relative to the total number of distinct elements
     * @param confidence the confidence in the result to not exceed the relative error
     */
    public CountMinSketchFn<InputT> withAccuracy(double epsilon, double confidence) {
      if (epsilon <= 0D) {
        throw new IllegalArgumentException("The relative error must be positive");
      }

      if (confidence <= 0D || confidence >= 1D) {
        throw new IllegalArgumentException("The confidence must be between 0 and 1");
      }
      return new CountMinSketchFn<>(inputCoder, epsilon, confidence);
    }

    @Override
    public Sketch<InputT> createAccumulator() {
      return Sketch.create(epsilon, confidence);
    }

    @Override
    public Sketch<InputT> addInput(Sketch<InputT> accumulator, InputT element) {
      accumulator.add(element, inputCoder);

      return accumulator;

View on GitHub (pinned to 12126d8942)

Solutions

1. Pass a positive epsilon, e.g. withAccuracy(0.01, 0.999) for 1% relative error.
2. Validate config-derived epsilon values before building the pipeline and fail fast with a clear message.
3. Sanity-check computations that produce epsilon (avoid integer division truncating to 0).

Example fix

// before
sketch.withAccuracy(0, 0.999); // throws
// after
sketch.withAccuracy(0.01, 0.999); // 1% relative error, 99.9% confidence

if (!(epsilon > 0D)) throw new IllegalArgumentException("epsilon must be > 0, got " + epsilon);
sketch.withAccuracy(epsilon, confidence);

try { sketch.withAccuracy(eps, conf); } catch (IllegalArgumentException e) { /* fall back to default accuracy */ }

When it happens

Trigger: Calling withAccuracy(0, 0.99) or withAccuracy(-0.01, 0.99), or accidentally passing a computed epsilon that evaluates to 0 (e.g. integer division or an uninitialized config value cast to double).

Common situations: Accuracy parameters read from config files/flags where a zero or negative default leaked through; typos like withAccuracy(0D, confidence); unit confusion producing negative values.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• The confidence must be between 0 and 1
• Coder must be deterministic to perform this sketch.${e.getMe
• The accumulators cannot be merged:${e.getMessage()}
• Pipeline update will not be possible because the following t
• One or more ErrorHandlers aren't closed, and this pipeline c

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/5a210056ccfbaadf. Report an issue: GitHub.