Heap dump detected but no upload directory was provided.

Error message

Heap dump {} detected but no upload directory was provided.

What it means

MemoryMonitor detected a heap dump file at the default local path but the uploadFilePath (remote destination directory) was never configured, so the dump cannot be shipped off the runner. The dump stays on local disk and will not be uploaded. This is a configuration-gap warning rather than a thrown exception.

Solutions

Set the heap dump upload path pipeline option (uploadFilePath) to a supported FileSystems destination (e.g. gs://bucket/path).
If off-runner retention is not needed, fetch the dump manually from the local default heap dump path before the worker is torn down.
Alternatively disable heap dumping so no orphan local dumps are produced.

Example fix

// before: no upload dir configured
PipelineOptions options = PipelineOptionsFactory.create();
// after: provide upload directory
options.as(HarnessOptions.class).setHeapDumpUploadPath("gs://my-bucket/heapdumps");

Defensive patterns

Strategy: validation

Validate before calling

// before enabling heap dumping, ensure the upload path option is set
if (options.as(HarnessOptions.class).getHeapDumpUploadPath() == null) {
  throw new IllegalArgumentException("heapDumpUploadPath must be set when heap dumping is enabled");
}

Prevention

Always set heapDumpUploadPath alongside heap-dump options
Use a supported FileSystems scheme (gs://, s3://) with the connector on the classpath
Add the option to your pipeline templates so it is not dropped

When it happens

Trigger: A heap dump was produced (heap dump on OOM enabled / dump triggered) while MemoryMonitor.fromOptions was constructed without the --heapDumpUploadPath (uploadFilePath) option; tryUploadHeapDumpIfItExists then finds localSource.exists() with uploadFilePath == null.

Common situations: Users enabling heap dumping in tests or local runs and forgetting to set the upload directory; a runner/template where the upload path option was dropped from pipeline 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/f636a56a8bff5382. Report an issue: GitHub.

Appendix: source

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

        if (interrupted) {
          Thread.currentThread().interrupt();
        }
      }
    }
  }

  private File getDefaultHeapDumpPath() {
    return new File(localDumpFolder, "heap_dump.hprof");
  }

  @VisibleForTesting
  boolean tryUploadHeapDumpIfItExists() {
    boolean uploadedHeapDump = false;
    File localSource = getDefaultHeapDumpPath();
    LOG.info("Looking for heap dump at {}", localSource);
    if (localSource.exists()) {
      if (uploadFilePath == null) {
        LOG.warn("Heap dump {} detected but no upload directory was provided.", localSource);
      } else {
        String remoteDest =
            String.format("%s/heap_dump%s.hprof", uploadFilePath, UUID.randomUUID());
        if (gzipCompress) {
          remoteDest = remoteDest + ".gz";
        }
        LOG.warn(
            "Heap dump {} of {}MB detected, attempting to upload file to {}",
            localSource,
            localSource.length() / 1024 / 1024,
            remoteDest);
        ResourceId resource = FileSystems.matchNewResource(remoteDest, false);
        try {
          uploadFile(localSource, resource, gzipCompress);
          uploadedHeapDump = true;
          LOG.warn("Heap dump {} uploaded to {}", localSource, remoteDest);
        } catch (IOException e) {
          LOG.error("Error uploading heap dump to {}", remoteDest, e);

View on GitHub (pinned to 12126d8942)