apache/beam · error

invalid scope

Error message

invalid scope

What it means

beam.TryCrossLanguage expands a cross-language transform via an external expansion service. Unlike the other Try* constructors, an invalid scope here is treated as a programmer-level invariant breach: instead of returning the error it panics with errors.New("invalid scope"). A valid Scope derived from the pipeline is mandatory to attach the external transform node to the graph.

Source

Thrown at sdks/go/pkg/beam/xlang.go:181

	namedOutputs, err := TryCrossLanguage(s, urn, payload, expansionAddr, namedInputs, namedOutputTypes)
	if err != nil {
		panic(errors.WithContextf(err, "tried cross-language for %v against %v and failed", urn, expansionAddr))
	}
	return namedOutputs
}

// TryCrossLanguage coordinates the core functions required to execute the cross-language transform.
// See CrossLanguage for user documentation.
func TryCrossLanguage(
	s Scope,
	urn string,
	payload []byte,
	expansionAddr string,
	namedInputs map[string]PCollection,
	namedOutputTypes map[string]FullType,
) (map[string]PCollection, error) {
	if !s.IsValid() {
		panic(errors.New("invalid scope"))
	}

	inputsMap, inboundLinks := graph.NamedInboundLinks(mapPCollectionToNode(namedInputs))
	outputsMap, outboundLinks := graph.NamedOutboundLinks(s.real, namedOutputTypes)

	// Set the coder for outbound links for downstream validation.
	for n, i := range outputsMap {
		c := NewCoder(namedOutputTypes[n])
		outboundLinks[i].To.Coder = c.coder
	}

	ext := graph.ExternalTransform{
		Urn:           urn,
		Payload:       payload,
		ExpansionAddr: expansionAddr,
	}.WithNamedInputs(inputsMap).WithNamedOutputs(outputsMap)

	// Adding an edge in the graph corresponding to the ExternalTransform

View on GitHub (pinned to 12126d8942)

Solutions

1. Pass a real scope: s := p.Root().Scope("xlang") obtained from the same pipeline whose PCollections are in namedInputs.
2. Recover from panics only at a top-level boundary if you must; the correct fix is initializing the scope, not catching the panic.
3. Ensure the scope and all named input PCollections come from one pipeline; scopes from a different pipeline can also produce invalid graph state.
4. Wrap cross-language construction in a helper that checks s.IsValid() first and returns a descriptive error before calling TryCrossLanguage.

Example fix

// before
var s beam.Scope
beam.CrossLanguage(s, "beam:transform:xxx:v1", payload, addr, inputs, outs) // panic

// after
s := p.Root().Scope("external")
beam.CrossLanguage(s, "beam:transform:xxx:v1", payload, addr, inputs, outs)

if !s.IsValid() {
    return fmt.Errorf("TryCrossLanguage panics on invalid scope; derive s from beam.NewPipeline().Root()")
}

When it happens

Trigger: Calling beam.TryCrossLanguage(s, urn, payload, addr, inputs, outputTypes) with a zero beam.Scope (s.IsValid() == false); the panic fires immediately at the entry of the function.

Common situations: Building cross-language calls in helpers that receive beam.Scope by value but are handed an uninitialized scope; scopes constructed before beam.NewPipeline(); forgetting that unlike other Try* functions this one panics rather than returns an error, so no recover-friendly error path exists.

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
• res.GetError()
• create has no values
• invalid scope
• invalid scope

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