{"record":{"id":"9dacae4df6099a22","repo":"apache/beam","slug":"maxcachememoryusagepercent-must-be-between-0-and-100","errorCode":null,"errorMessage":"--maxCacheMemoryUsagePercent must be between 0 and 100.","messagePattern":"--maxCacheMemoryUsagePercent must be between 0 and 100\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/options/SdkHarnessOptions.java","lineNumber":264,"sourceCode":"   * <p>If the {@link Runtime} provides a maximum amount of memory (typically specified with {@code\n   * -Xmx} JVM argument), then {@link #getMaxCacheMemoryUsagePercent maxCacheMemoryUsagePercent}\n   * will be used to compute the upper bound as a percentage of the maximum amount of memory.\n   * Otherwise {@code 100} is returned.\n   */\n  class DefaultMaxCacheMemoryUsageMb implements MaxCacheMemoryUsageMb {\n    @Override\n    public int getMaxCacheMemoryUsage(PipelineOptions options) {\n      return getMaxCacheMemoryUsage(options, Runtime.getRuntime().maxMemory());\n    }\n\n    @VisibleForTesting\n    int getMaxCacheMemoryUsage(PipelineOptions options, long maxMemory) {\n      if (maxMemory == Long.MAX_VALUE) {\n        return 100;\n      }\n      float maxPercent = options.as(SdkHarnessOptions.class).getMaxCacheMemoryUsagePercent();\n      if (maxPercent < 0 || maxPercent > 100) {\n        throw new IllegalArgumentException(\n            \"--maxCacheMemoryUsagePercent must be between 0 and 100.\");\n      }\n      return (int) (maxMemory / 1048576. * maxPercent / 100.);\n    }\n  }\n\n  /**\n   * Defines a log level override for a specific class, package, or name.\n   *\n   * <p>The SDK harness supports a logging hierarchy based off of names that are \".\" separated. It\n   * is a common pattern to have the logger for a given class share the same name as the class\n   * itself. Given the classes {@code a.b.c.Foo}, {@code a.b.c.Xyz}, and {@code a.b.Bar}, with\n   * loggers named {@code \"a.b.c.Foo\"}, {@code \"a.b.c.Xyz\"}, and {@code \"a.b.Bar\"} respectively, we\n   * can override the log levels:\n   *\n   * <ul>\n   *   <li>for {@code Foo} by specifying the name {@code \"a.b.c.Foo\"} or the {@link Class}\n   *       representing {@code a.b.c.Foo}.","sourceCodeStart":246,"sourceCodeEnd":282,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/options/SdkHarnessOptions.java#L246-L282","documentation":"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.","triggerScenarios":"Calling getMaxCacheMemoryUsage(options, maxMemory) after setting SdkHarnessOptions.setMaxCacheMemoryUsagePercent(p) with p < 0 or p > 100 (e.g. 150 or -5).","commonSituations":"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.","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"],"exampleFix":"// before\noptions.as(SdkHarnessOptions.class).setMaxCacheMemoryUsagePercent(150);\n// after\noptions.as(SdkHarnessOptions.class).setMaxCacheMemoryUsagePercent(90); // or (int)(0.9*100)","handlingStrategy":"validation","validationCode":"float p = options.as(SdkHarnessOptions.class).getMaxCacheMemoryUsagePercent();\nif (p < 0 || p > 100) throw new IllegalArgumentException(\"maxCacheMemoryUsagePercent must be in [0,100], got \" + p);","typeGuard":"boolean isValidPercent(float p) { return p >= 0f && p <= 100f; }","tryCatchPattern":null,"preventionTips":["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"],"tags":["java","apache-beam","pipeline-options","validation"],"backgroundTag":"value-out-of-range","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"}