What causes "sample period should be greater than 1ms, got %v" in apache/beam?

Pass an explicit time.Duration of at least time.Millisecond, e.g. SampleInterval(time.Millisecond).

sample period should be greater than 1ms, got

Error message

sample period should be greater than 1ms, got %v

What it means

SampleInterval sets the DoFn metrics sampling period for the Beam Go harness (default 200ms). This error is returned when the requested period is below 1ms, which the sampler cannot honor; the library refuses to enable the hook with such a value.

Solutions

Pass an explicit time.Duration of at least time.Millisecond, e.g. SampleInterval(time.Millisecond).
If you wrote SampleInterval(200), change it to SampleInterval(200 * time.Millisecond).
If you want less sampling overhead, raise the interval (default 200ms) rather than lowering it below 1ms.

Example fix

// before
SampleInterval(100)
// after
SampleInterval(100 * time.Millisecond)

Defensive patterns

Strategy: validation

Validate before calling

func validSamplePeriod(d time.Duration) bool { return d >= time.Millisecond }

Try / catch

if err := harnessopts.SampleInterval(p); err != nil { return fmt.Errorf("SampleInterval(%v): %w", p, err) }

Prevention

Always pass time.Duration values with explicit units; never pass bare integers.
Clamp requested periods to a floor of time.Millisecond before calling.

When it happens

Trigger: Calling SampleInterval with a time.Duration smaller than time.Millisecond, e.g. SampleInterval(500 * time.Microsecond) or SampleInterval(0).

Common situations: Passing a bare integer (nanoseconds in Go's Duration) instead of a time.Duration, e.g. SampleInterval(100) meaning 100ns, when the developer intended 100ms.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at sdks/go/pkg/beam/util/harnessopts/sampler.go:33

package harnessopts

import (
	"fmt"
	"time"

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

const (
	samplePeriodHook = "beam:go:hook:dofnmetrics:sampletime"
)

// SampleInterval sets the sampling time period (greater than 1ms) for DoFn metrics sampling.
// Default value is 200ms.
func SampleInterval(samplePeriod time.Duration) error {
	if samplePeriod < time.Millisecond {
		return fmt.Errorf("sample period should be greater than 1ms, got %v", samplePeriod)
	}
	sampleTime := samplePeriod.String()
	// The hook itself is defined in beam/core/runtime/harness/sampler_hook.go
	return hooks.EnableHook(samplePeriodHook, sampleTime)
}

View on GitHub (pinned to 12126d8942)