apache/beam · error

invalid scope

Error message

invalid scope

What it means

TryCoGroupByKey (used by TryGroupByKey and CoGroupByKey) validates the Scope before inserting a CoGBK transform into the pipeline graph. If the scope is invalid (zero value or from a failed construction), the transform cannot be attached, so the error is returned wrapped with additional CoGBK context naming the scope.

Source

Thrown at sdks/go/pkg/beam/gbk.go:74

// an error on failure.
func TryGroupByKey(s Scope, a PCollection) (PCollection, error) {
	return TryCoGroupByKey(s, a)
}

// CoGroupByKey inserts a CoGBK transform into the pipeline.
func CoGroupByKey(s Scope, cols ...PCollection) PCollection {
	return Must(TryCoGroupByKey(s, cols...))
}

func addCoGBKCtx(err error, s Scope) error {
	return errors.WithContextf(err, "inserting CoGroupByKey in scope %s", s)
}

// TryCoGroupByKey inserts a CoGBK transform into the pipeline. Returns
// an error on failure.
func TryCoGroupByKey(s Scope, cols ...PCollection) (PCollection, error) {
	if !s.IsValid() {
		return PCollection{}, addCoGBKCtx(errors.New("invalid scope"), s)
	}
	if len(cols) < 1 {
		return PCollection{}, addCoGBKCtx(errors.New("need at least 1 pcollection"), s)
	}
	for i, in := range cols {
		if !in.IsValid() {
			return PCollection{}, addCoGBKCtx(errors.Errorf("invalid pcollection to CoGBK: index %v", i), s)
		}
	}

	var in []*graph.Node
	for _, s := range cols {
		in = append(in, s.n)
	}

	edge, err := graph.NewCoGBK(s.real, s.scope, in)
	if err != nil {
		return PCollection{}, err

View on GitHub (pinned to 12126d8942)

Solutions

1. Pass a valid scope from beam.NewPipeline() or a child scope created via beam.Scope("label") as the first argument.
2. Check s.IsValid() before calling; if false, retrace scope creation in your code.
3. Verify you are not mixing PCollections/scopes from two different pipelines — build all inputs within the same pipeline.

Example fix

// before
var s beam.Scope
res := beam.CoGroupByKey(s, a, b) // invalid scope

// after
p := beam.NewPipeline()
res := beam.CoGroupByKey(p, a, b)

if !s.IsValid() {
	return fmt.Errorf("cannot CoGroupByKey: invalid scope %v", s)
}
out := beam.CoGroupByKey(s, cols...)

func validScope(s beam.Scope) bool { return s.IsValid() }

When it happens

Trigger: beam.CoGroupByKey(s, cols...) or beam.TryCoGroupByKey(s, cols...) / TryGroupByKey where s is a zero-value Scope{}, a Scope obtained from an errored call, or a scope whose parent pipeline was not created via beam.NewPipeline().

Common situations: Reusing a Scope captured from another pipeline; passing a Scope struct member that was never assigned; ignoring an earlier error that returned PCollection{} with an invalid embedded scope and then trying to group it.

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

• invalid scope
• need at least 1 pcollection
• Invalid scope
• empty chunk
• combine does not support side inputs

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