apache/beam · error

failed to merge windows, got: %v

Error message

failed to merge windows, got: %v

What it means

At FinishBundle, if the CoGBK input uses session windowing, the node merges accumulated windows via mergeWindows. Any error from that merge (inconsistent window state, failures hashing/comparing session windows) is surfaced as 'failed to merge windows, got: %v' and fails the bundle.

Source

Thrown at sdks/go/pkg/beam/runners/direct/gbk.go:105

	}
	key := buf.String()
	g, ok := m[key]
	if !ok {
		g = &group{
			key:    exec.FullValue{Elm: elm.Elm, Timestamp: elm.Timestamp, Windows: ws},
			values: make([][]exec.FullValue, len(n.Edge.Input)),
		}
		m[key] = g
	}
	return g, nil
}

func (n *CoGBK) FinishBundle(ctx context.Context) error {
	winKind := n.Edge.Input[0].From.WindowingStrategy().Fn.Kind
	if winKind == window.Sessions {
		mergeMap, mergeErr := n.mergeWindows()
		if mergeErr != nil {
			return errors.Errorf("failed to merge windows, got: %v", mergeErr)
		}
		if reprocessErr := n.reprocessByWindow(mergeMap); reprocessErr != nil {
			return errors.Errorf("failed to reprocess with merged windows, got :%v", reprocessErr)
		}
	}
	for key, g := range n.m {
		values := make([]exec.ReStream, len(g.values))
		for i, list := range g.values {
			values[i] = &exec.FixedReStream{Buf: list}
		}
		if err := n.Out.ProcessElement(ctx, &g.key, values...); err != nil {
			return err
		}
		delete(n.m, key)
	}
	return n.Out.FinishBundle(ctx)
}

View on GitHub (pinned to 12126d8942)

Solutions

1. Read the embedded mergeErr to see which windows/state failed to merge.
2. Validate your session gap duration and that the WindowFn is a standard window.Sessions strategy.
3. Reduce overlapping/unbounded session accumulation or switch the runner (Dataflow/Flink handle merging natively).
4. Upgrade the Beam SDK — session-merging bugs in the direct runner's CoGBK have been fixed over releases.

Example fix

// before
window.NewSessions(0 * time.Second) // degenerate gap causes merge issues
// after
window.NewSessions(5 * time.Minute)

err := plan.Execute(ctx, "", exec.DataContext{})
if err != nil && strings.Contains(err.Error(), "failed to merge windows") {
    log.Printf("session merge failed; check session WindowFn/gap: %v", err)
}

When it happens

Trigger: FinishBundle on a CoGBK node whose input windowing strategy Kind is window.Sessions and where n.mergeWindows() returns an error — e.g. session windows that cannot be consistently merged from the buffered per-key data.

Common situations: Session-windowed CoGBK pipelines with many overlapping windows; pipelines combining sessions with late data; bugs or edge cases in custom session WindowFns; large in-memory session state in the direct runner.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• failed to reprocess with merged windows, got :%v
• failed getGroup for %v: %v
• error encoding pane %v: non-speculative index value must be
• failed to map main input window to side input window with Wi
• mismatched CoGBK windowing strategies: %v, want %v

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