Heap dumps are requested with --enableHeapDumps but neither…

Error message

Heap dumps are requested with --enableHeapDumps but neither --remoteHeapDumpLocation nor --tempLocation was provided to specify where to copy captured heap dumps to.

What it means

MemoryMonitor.fromOptions() enables heap dump capture only when it knows where to put them; if --enableHeapDumps is set but no --remoteHeapDumpLocation or --tempLocation is configured, heap dumps cannot be uploaded and this warning is logged while heap dumping stays disabled (canDumpHeap remains false).

Solutions

Set --tempLocation (e.g. gs://bucket/temp) when enabling --enableHeapDumps.
Or set --remoteHeapDumpLocation to an explicit upload path.
Verify via pipeline options that portableOptions.getTempLocation() is non-null at launch.
Use jmap/kubectl cp to capture heap dumps manually if cloud temp storage is unavailable.

Example fix

// before
--enableHeapDumps=true
// after
--enableHeapDumps=true --tempLocation=gs://my-bucket/temp

Defensive patterns

Strategy: validation

Validate before calling

// Check options before enabling heap dumps
PortablePipelineOptions p = options.as(PortablePipelineOptions.class);
if (p.getEnableHeapDumps() && p.getTempLocation() == null && p.getRemoteHeapDumpLocation() == null) {
  throw new IllegalArgumentException("--enableHeapDumps requires --tempLocation or --remoteHeapDumpLocation");
}

Prevention

Always pair --enableHeapDumps with --tempLocation or --remoteHeapDumpLocation
Validate pipeline options at job submission time
Document required flags in your launch templates
Capture dumps manually when no cloud temp location is available

When it happens

Trigger: PortablePipelineOptions.setEnableHeapDumps(true) is passed to the SDK harness without setting remoteHeapDumpLocation or a tempLocation from which an upload path can be derived.

Common situations: Users enabling heap dumps for OOM debugging on Dataflow/Flink/Spark runners but forgetting --tempLocation; configs migrated between runners where tempLocation semantics differ; CLI flags set programmatically with incomplete options.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

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

   */
  @VisibleForTesting final @Nullable String uploadFilePath;

  @VisibleForTesting final File localDumpFolder;

  @VisibleForTesting final boolean gzipCompress;

  public static MemoryMonitor fromOptions(PipelineOptions options) {
    SdkHarnessOptions sdkHarnessOptions = options.as(SdkHarnessOptions.class);
    @Nullable String uploadFilePath = sdkHarnessOptions.getRemoteHeapDumpLocation();
    if (uploadFilePath == null) {
      uploadFilePath = options.getTempLocation();
    }
    PortablePipelineOptions portableOptions = options.as(PortablePipelineOptions.class);
    boolean canDumpHeap = false;
    File localDumpFolder = getHeapDumpDir();
    if (portableOptions.getEnableHeapDumps()) {
      if (uploadFilePath == null) {
        LOG.warn(
            "Heap dumps are requested with --enableHeapDumps but neither --remoteHeapDumpLocation nor "
                + "--tempLocation was provided to specify where to copy captured heap dumps to.");
      } else {
        try {
          Files.createDirectories(localDumpFolder.toPath());
          canDumpHeap = true;
        } catch (Exception e) {
          LOG.warn(
              "Encountered exception creating directory for heap dumps, disabling heap dumping.",
              e);
        }
      }
    }

    double gcThrashingPercentagePerPeriod = sdkHarnessOptions.getGCThrashingPercentagePerPeriod();
    return new MemoryMonitor(
        new SystemGCStatsProvider(),
        DEFAULT_SLEEP_TIME_MILLIS,

View on GitHub (pinned to 12126d8942)