{"record":{"id":"80ba563386fcc5d0","repo":"apache/beam","slug":"invalid-scope","errorCode":null,"errorMessage":"invalid scope","messagePattern":"invalid scope","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"sdks/go/pkg/beam/external.go","lineNumber":40,"sourceCode":")\n\n// External defines a Beam external transform. The interpretation of this primitive is runner\n// specific. The runner is responsible for parsing the payload based on the\n// URN provided to implement the behavior of the operation. Transform\n// libraries should expose an API that captures the user's intent and serialize\n// the payload as a byte slice that the runner will deserialize.\n//\n// Use ExternalTagged if the runner will need to associate the PTransforms local PCollection tags\n// with values in the payload.\nfunc External(s Scope, urn string, payload []byte, in []PCollection, out []FullType, bounded bool) []PCollection {\n\treturn MustN(TryExternal(s, urn, payload, in, out, bounded))\n}\n\n// TryExternal attempts to perform the work of External, returning an error indicating\n// why the operation failed.\nfunc TryExternal(s Scope, urn string, payload []byte, in []PCollection, out []FullType, bounded bool) ([]PCollection, error) {\n\tif !s.IsValid() {\n\t\treturn nil, errors.New(\"invalid scope\")\n\t}\n\tfor i, col := range in {\n\t\tif !col.IsValid() {\n\t\t\treturn nil, errors.Errorf(\"invalid pcollection to external: index %v\", i)\n\t\t}\n\t}\n\n\tvar ins []*graph.Node\n\tfor _, col := range in {\n\t\tins = append(ins, col.n)\n\t}\n\tedge := graph.NewExternal(s.real, s.scope, &graph.Payload{URN: urn, Data: payload}, ins, out, bounded)\n\n\tvar ret []PCollection\n\tfor _, out := range edge.Output {\n\t\tc := PCollection{out.To}\n\t\tc.SetCoder(NewCoder(c.Type()))\n\t\tret = append(ret, c)","sourceCodeStart":22,"sourceCodeEnd":58,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/go/pkg/beam/external.go#L22-L58","documentation":"TryExternal validates that the provided Scope is valid before constructing an external (cross-language) transform. An invalid or default-constructed Scope (one not bound to a real pipeline/vertex) is rejected with 'invalid scope'.","triggerScenarios":"Calling beam.External/TryExternal with a zero-value Scope, a Scope whose s.IsValid() is false (e.g. Scope{} created directly, or a scope from a finished/closed composite).","commonSituations":"Creating a Scope with var s beam.Scope instead of deriving it from the pipeline (beam.Scope(p.Root())); passing a scope from another pipeline; using a composite scope after its construction completed.","solutions":["Derive the scope from the pipeline: use p.Root() or beam.Scope(parent)","Never pass a zero-value Scope{}; always obtain scopes through the beam API","Check col/scope validity early in helper functions with s.IsValid()","If scoping inside composites, create the child scope before the composite body completes"],"exampleFix":"// before\nvar s beam.Scope // zero value, invalid\nbeam.External(s, urn, payload, in, out, true)\n// after\ns := beam.Scope(p.Root())\nbeam.External(s, urn, payload, in, out, true)","handlingStrategy":"validation","validationCode":"if !s.IsValid() {\n    return errors.New(\"scope must be derived from p.Root() or beam.Scope(parent), not a zero-value Scope\")\n}","typeGuard":"func validScope(s beam.Scope) bool { return s.IsValid() }","tryCatchPattern":"cols, err := beam.TryExternal(s, urn, payload, in, out, bounded)\nif err != nil {\n    if strings.Contains(err.Error(), \"invalid scope\") { return fmt.Errorf(\"scope not bound to pipeline: %w\", err) }\n    return err\n}","preventionTips":["Always obtain scopes from the pipeline API, never declare `var s beam.Scope`","Validate scopes at helper-function boundaries with s.IsValid()","Keep scope and PCollection on the same pipeline instance","Prefer Try* variants to surface scope errors as values"],"tags":["go","apache-beam","scope","validation"],"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-14T16:17:12.679Z"}