{"record":{"id":"61678c9062547841","repo":"apache/beam","slug":"dofns-that-observe-windows-must-be-invoked-with-single","errorCode":null,"errorMessage":"DoFns that observe windows must be invoked with single window: %v","messagePattern":"DoFns that observe windows must be invoked with single window: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"sdks/go/pkg/beam/core/runtime/exec/fn.go","lineNumber":221,"sourceCode":"\treturn n.invokeWithOpts(ctx, pn, ws, ts, InvokeOpts{opt: opt, bf: bf, we: we, sa: sa, sr: sr, extra: extra})\n}\n\nfunc (n *invoker) invokeWithOpts(ctx context.Context, pn typex.PaneInfo, ws []typex.Window, ts typex.EventTime, opts InvokeOpts) (*FullValue, error) {\n\t// (1) Populate contexts\n\t// extract these to make things easier to read.\n\targs := n.args\n\tfn := n.fn\n\tin := n.in\n\n\tif n.ctxIdx >= 0 {\n\t\targs[n.ctxIdx] = ctx\n\t}\n\tif n.pnIdx >= 0 {\n\t\targs[n.pnIdx] = pn\n\t}\n\tif n.wndIdx >= 0 {\n\t\tif len(ws) != 1 {\n\t\t\treturn nil, errors.Errorf(\"DoFns that observe windows must be invoked with single window: %v\", opts.opt.Key.Windows)\n\t\t}\n\t\targs[n.wndIdx] = ws[0]\n\t}\n\tif n.etIdx >= 0 {\n\t\targs[n.etIdx] = ts\n\t}\n\tif n.bfIdx >= 0 {\n\t\targs[n.bfIdx] = opts.bf\n\t}\n\tif n.weIdx >= 0 {\n\t\targs[n.weIdx] = opts.we\n\t}\n\n\tif n.spIdx >= 0 {\n\t\tsp, err := opts.sa.NewStateProvider(ctx, opts.sr, ws[0], opts.opt)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}","sourceCodeStart":203,"sourceCodeEnd":239,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/go/pkg/beam/core/runtime/exec/fn.go#L203-L239","documentation":"When a DoFn declares a window parameter (n.wndIdx >= 0), invokeWithOpts requires the element to carry exactly one window, since Beam Go cannot pick a representative window for a multi-window element. If len(ws) != 1, this error is returned instead of invoking the DoFn.","triggerScenarios":"A DoFn signature includes a beam window parameter, and invokeWithOpts receives opts whose opts.opt.Key.Windows has length 0 or >1 — e.g. an element in multiple windows, or an empty window slice from a bad source.","commonSituations":"Elements fired into multiple overlapping windows while the DoFn observes windows; custom sources producing empty window slices; SDK-internal bug where window merging yields multi-window elements at invocation time.","solutions":["Ensure elements are exploded to single windows before reaching window-observing DoFns (use ExplodeWindows semantics appropriately)","Check whether the DoFn genuinely needs the window parameter; remove it if not","Verify upstream windowing/merging logic (sliding/overlapping windows) is intended","Report to Beam if a stock transform produces multi-window elements here (possible bug)"],"exampleFix":"// before\nfunc (fn *myFn) ProcessElement(ctx context.Context, w beam.Window, v string) { ... }\n// used with overlapping windows producing multi-window elements\n// after\nfunc (fn *myFn) ProcessElement(ctx context.Context, v string) { ... } // drop window param\n// or explode elements so each invocation sees exactly one window","handlingStrategy":"validation","validationCode":"// before invoking a window-observing DoFn, assert single-window\nfunc hasSingleWindow(ws []beam.Window) bool { return len(ws) == 1 }","typeGuard":"func singleWindowOnly(ws []beam.Window) (beam.Window, bool) {\n    if len(ws) != 1 { return nil, false }\n    return ws[0], true\n}","tryCatchPattern":"// on the runner side, catch this invocation failure\nif err != nil && strings.Contains(err.Error(), \"must be invoked with single window\") {\n    return fmt.Errorf(\"explode windows before this DoFn: %w\", err)\n}","preventionTips":["Only add a beam.Window parameter when truly needed","Avoid overlapping-window designs feeding window-observing DoFns directly","Explode elements so each invocation sees one window","Add signature review for DoFns using window/timestamp parameters"],"tags":["beam","go","windowing","dofn"],"backgroundTag":"invalid-argument-value","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}