What causes "Failed to sample: %v" in apache/beam?

Check the wrapped inner error from the message to find the real sampler failure cause.

Failed to sample

Error message

Failed to sample: %v

What it means

The harness stateSampler goroutine periodically invokes s.sampler.Sample(ctx, t) on each ticker tick to sample worker state for progress/timeout reporting. If Sample returns an error, the goroutine returns errors.Errorf("Failed to sample: %v", err). This is a secondary monitoring feature; the message surfaces the reason state sampling could not run, not a pipeline data-processing failure itself.

Solutions

Check the wrapped inner error from the message to find the real sampler failure cause.
If it appears only at shutdown, treat it as benign noise and ignore it.
If it recurs during steady state, report/upgrade — it usually indicates an SDK bug in sampler state handling.
Ensure the harness is not being killed/restarted mid-sample (stabilize the worker environment).
Reduce sampling frequency or disable sampling where the runner supports it in constrained environments.

Defensive patterns

Strategy: try-catch

Try / catch

if err := worker.Run(ctx, opts); err != nil {
    if strings.Contains(err.Error(), "Failed to sample") && ctx.Err() != nil {
        return nil // sampling raced with shutdown; benign
    }
    return err
}

Prevention

Ignore this error when it coincides with harness shutdown/cancellation.
Keep worker processes stable (no mid-run kills) so sampling doesn't race teardown.
If recurring in steady state, upgrade the SDK — usually an SDK-side sampler bug.
Cross-check the inner error text in the message for the actual root cause.

When it happens

Trigger: The ticker fires and s.sampler.Sample(ctx, t) returns an error — typically because the underlying sampling mechanism (reading sampler state or the context) fails while the harness is running bundles.

Common situations: Sampling racing against harness shutdown (context cancelled between ctx.Done and Sample); sampler state invalidated during bundle/process teardown; rare runtime faults in the state sampler hook.

Related errors

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

Appendix: source

Thrown at sdks/go/pkg/beam/core/runtime/harness/sampler.go:46

}

func newSampler(store *metrics.Store, elementProcessingTimeout time.Duration) *stateSampler {
	return &stateSampler{sampler: metrics.NewSampler(store, elementProcessingTimeout), done: make(chan int)}
}

func (s *stateSampler) start(ctx context.Context, t time.Duration) error {
	ticker := time.NewTicker(t)
	defer ticker.Stop()
	for {
		select {
		case <-s.done:
			return nil
		case <-ctx.Done():
			return nil
		case <-ticker.C:
			err := s.sampler.Sample(ctx, t)
			if err != nil {
				return errors.Errorf("Failed to sample: %v", err)
			}
		}
	}
}

func (s *stateSampler) stop() {
	close(s.done)
}

View on GitHub (pinned to 12126d8942)