apache/beam · error · IllegalArgumentException

Expected size >= 0 but received ${size}.

Error message

Expected size >= 0 but received ${size}.

What it means

This validation is used by default restriction-tracker helpers for splittable DoFns: a restriction's reported size must be non-negative for progress/fraction estimation. validateSize throws IllegalArgumentException when a negative size is claimed.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/reflect/ByteBuddyDoFnInvokerFactory.java:576

  }

  public static class DefaultGetSize {
    /** Uses {@link HasProgress} to produce the size. */
    @SuppressWarnings("unused")
    public static <InputT, OutputT> double invokeGetSize(
        DoFnInvoker.ArgumentProvider<InputT, OutputT> argumentProvider) {
      if (argumentProvider.restrictionTracker() instanceof HasProgress) {
        return ((HasProgress) argumentProvider.restrictionTracker())
            .getProgress()
            .getWorkRemaining();
      } else {
        return 0.0;
      }
    }

    public static double validateSize(double size) {
      if (size < 0) {
        throw new IllegalArgumentException(
            String.format("Expected size >= 0 but received %s.", size));
      }
      return size;
    }
  }

  /**
   * Generates a type suffix string for use in invoker class names.
   *
   * <p>This creates a unique suffix based on the input and output type descriptors to avoid class
   * name collisions when the same DoFn class is used with different generic types.
   *
   * <p>The format is: {@code DoFnInvoker$<8-digit hex hash>}
   *
   * @param inputType the input type descriptor
   * @param outputType the output type descriptor
   * @return a string suffix for the invoker class name
   */

View on GitHub (pinned to 12126d8942)

Solutions

1. Clamp the reported size to >= 0 in the RestrictionTracker (Math.max(0, end - start)).
2. Fix the restriction computation so size is derived correctly from actual data bounds.
3. Return 0 for empty restrictions rather than a negative value.

Example fix

// before
public double getSize() { return end - start; } // negative if end < start
// after
public double getSize() { return Math.max(0, end - start); }

double size = tracker.currentRestriction().getBodySize();
if (size < 0) throw new IllegalStateException("restriction size must be >= 0, got " + size);

boolean isValidSize(double size) { return size >= 0 && !Double.isNaN(size); }

When it happens

Trigger: A custom RestrictionTracker or restriction reports a negative value from its size/progress method (e.g. end offset smaller than start), which the ByteBuddy delegation passes to validateSize.

Common situations: Miscomputed restriction in a custom splittable DoFn; overflow or unit mistakes when computing byte/element counts; empty input returning a negative sentinel.

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

• Missing required value for group [<group>]. At least one of
• --maxCacheMemoryUsagePercent must be between 0 and 100.
• GroupByEncryptedKey requires its input to use KvCoder
• the GroupByKey requires its output coder to be %s but found
• %s is splittable and uses state, but these are not compatibl

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