apache/beam · error · IllegalArgumentException

--maxCacheMemoryUsagePercent must be between 0 and 100.

Error message

--maxCacheMemoryUsagePercent must be between 0 and 100.

What it means

SdkHarnessOptions.maxCacheMemoryUsage computes the SDK harness cache size in MB from a user-supplied --maxCacheMemoryUsagePercent. This IllegalArgumentException is thrown because the configured percentage is outside the legal 0..100 range, so the cache fraction would be nonsensical (negative or over-full). Beam validates eagerly at pipeline construction time rather than producing a broken harness.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/options/SdkHarnessOptions.java:264

   * <p>If the {@link Runtime} provides a maximum amount of memory (typically specified with {@code
   * -Xmx} JVM argument), then {@link #getMaxCacheMemoryUsagePercent maxCacheMemoryUsagePercent}
   * will be used to compute the upper bound as a percentage of the maximum amount of memory.
   * Otherwise {@code 100} is returned.
   */
  class DefaultMaxCacheMemoryUsageMb implements MaxCacheMemoryUsageMb {
    @Override
    public int getMaxCacheMemoryUsage(PipelineOptions options) {
      return getMaxCacheMemoryUsage(options, Runtime.getRuntime().maxMemory());
    }

    @VisibleForTesting
    int getMaxCacheMemoryUsage(PipelineOptions options, long maxMemory) {
      if (maxMemory == Long.MAX_VALUE) {
        return 100;
      }
      float maxPercent = options.as(SdkHarnessOptions.class).getMaxCacheMemoryUsagePercent();
      if (maxPercent < 0 || maxPercent > 100) {
        throw new IllegalArgumentException(
            "--maxCacheMemoryUsagePercent must be between 0 and 100.");
      }
      return (int) (maxMemory / 1048576. * maxPercent / 100.);
    }
  }

  /**
   * Defines a log level override for a specific class, package, or name.
   *
   * <p>The SDK harness supports a logging hierarchy based off of names that are "." separated. It
   * is a common pattern to have the logger for a given class share the same name as the class
   * itself. Given the classes {@code a.b.c.Foo}, {@code a.b.c.Xyz}, and {@code a.b.Bar}, with
   * loggers named {@code "a.b.c.Foo"}, {@code "a.b.c.Xyz"}, and {@code "a.b.Bar"} respectively, we
   * can override the log levels:
   *
   * <ul>
   *   <li>for {@code Foo} by specifying the name {@code "a.b.c.Foo"} or the {@link Class}
   *       representing {@code a.b.c.Foo}.

View on GitHub (pinned to 12126d8942)

Solutions

Set --maxCacheMemoryUsagePercent to a value between 0 and 100 inclusive
If you meant a fraction, multiply by 100 (0.9 -> 90)
Clamp the value programmatically before building PipelineOptions

Example fix

// before
options.as(SdkHarnessOptions.class).setMaxCacheMemoryUsagePercent(150);
// after
options.as(SdkHarnessOptions.class).setMaxCacheMemoryUsagePercent(90); // or (int)(0.9*100)

Defensive patterns

Strategy: validation

Validate before calling

float p = options.as(SdkHarnessOptions.class).getMaxCacheMemoryUsagePercent();
if (p < 0 || p > 100) throw new IllegalArgumentException("maxCacheMemoryUsagePercent must be in [0,100], got " + p);

Type guard

boolean isValidPercent(float p) { return p >= 0f && p <= 100f; }

Prevention

Validate config percent fields at startup with an explicit range check
Store percentages as 0-100, not fractions
Add unit tests covering boundary values 0 and 100

When it happens

Trigger: Calling getMaxCacheMemoryUsage(options, maxMemory) after setting SdkHarnessOptions.setMaxCacheMemoryUsagePercent(p) with p < 0 or p > 100 (e.g. 150 or -5).

Common situations: Hand-editing pipeline options in YAML/JSON with a wrong value, expressing the value as a fraction (0.9 instead of 90), or templating a config where the percent variable is unbounded.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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