gcThrashingPercentagePerPeriod

Error message

gcThrashingPercentagePerPeriod: {} is not valid value. Not starting MemoryMonitor.

What it means

MemoryMonitor.run() validates gcThrashingPercentagePerPeriod and refuses to start the monitor if the value is <= 0 or >= 100, logging this warning and clearing the running flag. Consequently no GC-thrashing detection or memory monitoring occurs for the harness process. The threshold must be a percentage strictly between 0 and 100.

Solutions

Set gcThrashingPercentagePerPeriod to a value in (0, 100), e.g. 75 or the Beam default (~80), in your pipeline options.
If you intended to disable the monitor, remove the option rather than passing 0, or accept that monitoring is off.
Check any pipeline template/parameter substitution that may inject an empty or 0 value for this option.

Example fix

// before
--gcThrashingPercentagePerPeriod=0
// after
--gcThrashingPercentagePerPeriod=75

Defensive patterns

Strategy: validation

Validate before calling

int pct = options.getGcThrashingPercentagePerPeriod();
if (pct <= 0 || pct >= 100) throw new IllegalArgumentException("gcThrashingPercentagePerPeriod must be in (0,100), got " + pct);

Prevention

Validate pipeline option values in launcher code before submission
Use the Beam default (~80) unless you have a specific reason
Guard template parameter substitution against blank/0 values

When it happens

Trigger: The pipeline option supplying gcThrashingPercentagePerPeriod is set to 0, a negative number, 100, or higher — often via a misconfigured default or a template parameter injected as 0/blank-parsed value.

Common situations: Users disabling monitoring by setting the threshold to 0 (getting this warning instead), or YAML/JSON templates passing an unbounded value; copies of the option between runner-specific option classes carrying an invalid default.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at sdks/java/harness/src/main/java/org/apache/beam/fn/harness/status/MemoryMonitor.java:523

    File heapDumpFile = tryToDumpHeap();
    LOG.error(
        "Shutting down JVM after {} consecutive periods of measured GC thrashing. "
            + "Memory is {}. Heap dump {}.",
        thrashingCount,
        describeMemory(),
        heapDumpFile == null ? "not written" : ("written to '" + heapDumpFile + "'"));

    System.exit(1);
  }

  /** Runs this thread. */
  @Override
  public void run() {
    synchronized (waitingForStateChange) {
      Preconditions.checkState(!isRunning.getAndSet(true), "already running");

      if (this.gcThrashingPercentagePerPeriod <= 0 || this.gcThrashingPercentagePerPeriod >= 100) {
        LOG.warn(
            "gcThrashingPercentagePerPeriod: {} is not valid value. Not starting MemoryMonitor.",
            this.gcThrashingPercentagePerPeriod);
        isRunning.set(false);
      }

      waitingForStateChange.notifyAll();
    }

    // Within the memory monitor thread check to see if there is a pre-existing heap dump, and
    // attempt to upload it. Note that this will delay the first memory monitor check.
    tryUploadHeapDumpIfItExists();

    try {
      long lastTimeWokeUp = System.currentTimeMillis();
      long lastLog = -1;
      int currentThrashingCount = 0;
      while (true) {
        synchronized (waitingForStateChange) {

View on GitHub (pinned to 12126d8942)