apache/beam · error

invalid scope

Error message

invalid scope

What it means

validate() is the shared pre-flight check used by transform constructors such as TryParDo and TryCombinePerKey. It rejects the call with "invalid scope" when the passed beam.Scope is not valid — i.e. it is the zero Scope (created via var s beam.Scope) rather than one derived from a pipeline. A zero Scope has no underlying real scope, so transforms cannot be added to it.

Source

Thrown at sdks/go/pkg/beam/validate.go:50

	}
	return t.Components()[0], t.Components()[1]
}

// ValidateNonCompositeType panics if the type of the PCollection is not a
// composite type. It returns the type.
func ValidateNonCompositeType(col PCollection) typex.FullType {
	t := col.Type()
	if typex.IsComposite(t.Type()) {
		panic(fmt.Sprintf("pcollection must be of non-composite type: %v", col))
	}
	return t
}

// validate validates and processes the input collection and options. Private convenience
// function.
func validate(s Scope, col PCollection, opts []Option) ([]SideInput, map[string]reflect.Type, error) {
	if !s.IsValid() {
		return nil, nil, errors.New("invalid scope")
	}
	if !col.IsValid() {
		return nil, nil, errors.New("invalid main pcollection")
	}
	side, defs := parseOpts(opts)
	for i, in := range side {
		if !in.Input.IsValid() {
			return nil, nil, errors.Errorf("invalid side pcollection: index %v", i)
		}
	}
	typedefs, err := makeTypedefs(defs)
	if err != nil {
		return nil, nil, err
	}
	return side, typedefs, nil
}

func makeTypedefs(list []TypeDefinition) (map[string]reflect.Type, error) {

View on GitHub (pinned to 12126d8942)

Solutions

1. Obtain the scope from a real pipeline: p := beam.NewPipeline(); s := p.Root() (or s := scope.Scope("name")) before calling the transform.
2. Check each code path that builds the Scope and ensure it derives from beam.NewPipeline().Root(), never from a zero value.
3. Prefer Must-constructors so panics surface at construction with a stack trace pointing at the bad scope.
4. Guard library helpers with `if !s.IsValid() { return fmt.Errorf(...) }` of your own to fail fast with context.

Example fix

// before
var s beam.Scope
beam.ParDo0(s, &fn{}, col) // invalid scope

// after
p := beam.NewPipeline()
s := p.Root().Scope("myTransform")
beam.ParDo0(s, &fn{}, col)

if !s.IsValid() {
    return fmt.Errorf("transform requires a scope derived from beam.NewPipeline().Root()")
}

When it happens

Trigger: Calling beam.TryParDo / beam.TryCombinePerKey (or their Must wrappers) with a Scope obtained from var s beam.Scope, a struct field never initialized, or a Scope taken before pipeline.New() — anything where s.IsValid() is false.

Common situations: Refactoring a pipeline into a function that takes beam.Scope but callers pass an uninitialized value; embedding a Scope in a struct declared without initialization; constructing transforms in a package-level var before a pipeline exists; copy-paste code that forgot s := p.Root().

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

• empty pipeline
• create has no values
• invalid scope
• invalid main pcollection
• invalid side pcollection: index %v

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