{"record":{"id":"fa46e118f9d3564f","repo":"apache/beam","slug":"external-key-not-found-v","errorCode":null,"errorMessage":"external key not found %v","messagePattern":"external key not found (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"sdks/go/pkg/beam/core/runtime/graphx/serialize.go","lineNumber":672,"sourceCode":"\t\telm, err := decodeType(t.GetElement())\n\t\tif err != nil {\n\t\t\twrapped := errors.Wrap(err, \"bad element\")\n\t\t\treturn nil, errors.WithContextf(wrapped, \"decoding type %v\", t)\n\t\t}\n\t\treturn reflect.PtrTo(elm), nil\n\n\tcase v1pb.Type_SPECIAL:\n\t\tret, err := decodeSpecial(t.Special)\n\t\tif err != nil {\n\t\t\twrapped := errors.Wrap(err, \"bad element\")\n\t\t\treturn nil, errors.WithContextf(wrapped, \"decoding type %v\", t)\n\t\t}\n\t\treturn ret, nil\n\n\tcase v1pb.Type_EXTERNAL:\n\t\tret, ok := runtime.LookupType(t.ExternalKey)\n\t\tif !ok {\n\t\t\terr := errors.Errorf(\"external key not found %v\", t.ExternalKey)\n\t\t\treturn nil, errors.WithContextf(err, \"decoding type %v\", t)\n\t\t}\n\t\treturn ret, nil\n\n\tdefault:\n\t\terr := errors.Errorf(\"unexpected type kind %v\", t.Kind)\n\t\treturn nil, errors.WithContextf(err, \"failed to decode type %v\", t)\n\t}\n}\n\nfunc decodeSpecial(s v1pb.Type_Special) (reflect.Type, error) {\n\tswitch s {\n\tcase v1pb.Type_ERROR:\n\t\treturn reflectx.Error, nil\n\tcase v1pb.Type_CONTEXT:\n\t\treturn reflectx.Context, nil\n\tcase v1pb.Type_TYPE:\n\t\treturn reflectx.Type, nil","sourceCodeStart":654,"sourceCodeEnd":690,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/go/pkg/beam/core/runtime/graphx/serialize.go#L654-L690","documentation":"decodeType hits a v1pb.Type_EXTERNAL type whose ExternalKey is not present in the runtime type registry (runtime.LookupType returned false). The Beam graph references an external type that must have been registered via runtime.RegisterType before decoding, and it wasn't.","triggerScenarios":"Decoding a ModelPipeline containing Type_EXTERNAL whose ExternalKey was never registered in the decoding process via runtime.RegisterType(key, typ); decodeFn/decodeCustomCoder/decodeTypes propagate the failure.","commonSituations":"Cross-language or worker-side decoding where type registration code (usually in an init()) was not linked in; dropping an import that performed RegisterType; external type keys changed between SDK versions.","solutions":["Add runtime.RegisterType(<externalKey>, reflect.TypeOf(...)) for the missing key, ideally in an init() of an imported package","Ensure the package performing the registration is imported (blank import) in the decoding binary","Verify the ExternalKey string in the serialized graph matches the registered key exactly","Align SDK versions so the same registration code that encoded the graph is present at decode time"],"exampleFix":"// before: decoding binary without registration\nfunc main() { graphx.DecodeGraph(data) }\n\n// after\n//go:linkname nothing — just import the package that registers\nimport _ \"myproj/beam/typeregistry\" // contains init(){ runtime.RegisterType(\"mypkg.MyType\", reflect.TypeOf(MyType{})) }","handlingStrategy":"validation","validationCode":"// Before decoding, verify all external keys are registered\nfor _, key := range collectExternalKeys(proto) {\n    if _, ok := runtime.LookupType(key); !ok {\n        return fmt.Errorf(\"external type %q not registered; add a blank import of its registering package\", key)\n    }\n}","typeGuard":null,"tryCatchPattern":"if err := graphx.DecodeGraph(data, &p); err != nil {\n    var missing string\n    if _, e := fmt.Sscanf(err.Error(), \"external key not found %q\", &missing); e == nil {\n        return fmt.Errorf(\"register %q via runtime.RegisterType (blank import) before decoding\", missing)\n    }\n    return err\n}","preventionTips":["Put runtime.RegisterType calls in init() of dedicated packages and blank-import them in every binary that decodes graphs","Keep external key strings as constants shared by encoder and decoder","Watch for registration code lost when refactoring imports"],"tags":["beam","go","serialization","type-registry","graphx"],"backgroundTag":"resource-not-found","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}