apache/beam · error

invalid status for precombine %v: %v

Error message

invalid status for precombine %v: %v

What it means

LiftedCombine.ProcessElement (the precombine/lifted path) requires the node status to be Active, i.e., inside a started bundle. Processing elements outside an active bundle violates the lifecycle and returns this error.

Source

Thrown at sdks/go/pkg/beam/core/runtime/exec/combine.go:362

	n.cache = newLiftingCache(cacheMax, n.KeyCoder, n.WindowCoder)
	return nil
}

// StartBundle initializes the in memory cache of keys to accumulators.
func (n *LiftedCombine) StartBundle(ctx context.Context, id string, data DataContext) error {
	if err := n.Combine.StartBundle(ctx, id, data); err != nil {
		return err
	}
	n.cache.start()
	return nil
}

// ProcessElement takes a KV pair and combines values with the same key into an accumulator,
// caching them until the bundle is complete. If the cache grows too large, a random eviction
// policy is used.
func (n *LiftedCombine) ProcessElement(ctx context.Context, value *FullValue, values ...ReStream) error {
	if n.status != Active {
		return errors.Errorf("invalid status for precombine %v: %v", n.UID, n.status)
	}

	n.Combine.states.Set(n.Combine.ctx, metrics.ProcessBundle)

	// The cache layer in lifted combines implicitly observes windows. Process each individually.
	for _, w := range value.Windows {
		err := n.processElementPerWindow(ctx, value, w)
		if err != nil {
			return n.fail(err)
		}
	}
	return nil
}

func (n *LiftedCombine) processElementPerWindow(ctx context.Context, value *FullValue, w typex.Window) error {
	key, afv, notfirst, err := n.cache.lookup(value, w)
	if err != nil {
		return n.fail(err)

View on GitHub (pinned to 12126d8942)

Solutions

1. Drive the full lifecycle: Up, StartBundle, ProcessElement, FinishBundle.
2. Restart the bundle (StartBundle) if elements must be processed after FinishBundle.
3. Verify the plan executor isn't reusing a finished unit.

if err := lifted.ProcessElement(ctx, fv); err != nil {
	if strings.Contains(err.Error(), "invalid status for precombine") {
		// ensure StartBundle was called on the lifted combine
	}
	return err
}

When it happens

Trigger: Calling LiftedCombine.ProcessElement before StartBundle or after FinishBundle.

Common situations: Custom runners or tests invoking the lifted-combine unit directly without driving Up/StartBundle first.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• invalid status for combine merge %v: %v
• invalid status for combine extract %v: %v
• invalid status for combine convert %v: %v
• invalid status for combine %v: %v
• unable to infer CombineFn accumulator coder

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