max time between dumps

Error message

max time between dumps %v should be greater than or equal to sampling frequence %v

What it means

HeapDumpFrequency configures the diagnostics service's heap-dump sampling frequency and the maximum time between dumps. This error means the caller passed a maxTimeBetweenDumpsSeconds that is smaller than samplingFrequencySeconds, which is nonsensical: dumps would have to happen more often than the sampler checks. The library rejects the configuration before enabling the hook.

Solutions

Ensure maxTimeBetweenDumpsSeconds >= samplingFrequencySeconds in the call.
Check argument order; the first parameter is the sampling frequency, the second is the max time between dumps.
If you want dumps no more often than every N seconds, set maxTimeBetweenDumpsSeconds = N and samplingFrequencySeconds <= N.

Example fix

// before
HeapDumpFrequency(5, 2)
// after
HeapDumpFrequency(2, 5)

Defensive patterns

Strategy: validation

Validate before calling

func validDumpConfig(freq, maxTime int) bool { return maxTime >= freq }

Try / catch

if err := harnessopts.HeapDumpFrequency(freq, maxTime); err != nil { log.Fatalf("heap dump config rejected: %v", err) }

Prevention

Keep samplingFrequencySeconds <= maxTimeBetweenDumpsSeconds by construction (e.g. derive one from the other).
Validate both knobs in your config loader before enabling diagnostics.

When it happens

Trigger: Calling beam HarnessOpts HeapDumpFrequency(samplingFrequencySeconds, maxTimeBetweenDumpsSeconds) with maxTimeBetweenDumpsSeconds < samplingFrequencySeconds, e.g. HeapDumpFrequency(5, 1).

Common situations: Developers misread the parameter order and swap the two values, or tune the sampling frequency up after setting a small max-dump interval without revisiting the other knob.

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/b25c79e758fd3452. Report an issue: GitHub.

Appendix: source

Thrown at sdks/go/pkg/beam/util/harnessopts/heap_dump.go:35

import (
	"fmt"
	"strconv"

	"github.com/apache/beam/sdks/v2/go/pkg/beam/core/util/hooks"
)

const (
	diagnosticsHook = "beam:go:hook:diagnostics:heapDump"
)

// HeapDumpFrequency sets the sampling frequency for how often the diagnostics service checks if it
// should take a heap dump and the maximum allowable time between heap dumps.
// Setting the sampling frequency to <=0 disables the heap dump checks.
// The default value for the sampling frequency is 1 second, the default max time is 60 seconds.
func HeapDumpFrequency(samplingFrequencySeconds, maxTimeBetweenDumpsSeconds int) error {
	if maxTimeBetweenDumpsSeconds < samplingFrequencySeconds {
		return fmt.Errorf("max time between dumps %v should be greater than or equal to sampling frequence %v", maxTimeBetweenDumpsSeconds, samplingFrequencySeconds)
	}
	// The hook itself is defined in beam/core/runtime/harness/init/diagnostics_hook.go
	return hooks.EnableHook(diagnosticsHook, strconv.Itoa(samplingFrequencySeconds), strconv.Itoa(maxTimeBetweenDumpsSeconds))
}

View on GitHub (pinned to 12126d8942)