{"record":{"id":"53e6a9ea4677b0e2","repo":"temporalio/temporal","slug":"membership-upserts-require-all-fields","errorCode":null,"errorMessage":"membership upserts require all fields","messagePattern":"membership upserts require all fields","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"common/persistence/cluster_metadata_store.go","lineNumber":18,"sourceCode":"package persistence\n\nimport (\n\t\"context\"\n\t\"errors\"\n\n\t\"go.temporal.io/api/serviceerror\"\n\tpersistencespb \"go.temporal.io/server/api/persistence/v1\"\n\t\"go.temporal.io/server/common/log\"\n\t\"go.temporal.io/server/common/persistence/serialization\"\n)\n\nvar (\n\t// ErrInvalidMembershipExpiry is used when upserting new cluster membership with an invalid duration\n\tErrInvalidMembershipExpiry = errors.New(\"membershipExpiry duration should be atleast 1 second\")\n\n\t// ErrIncompleteMembershipUpsert is used when upserting new cluster membership with missing fields\n\tErrIncompleteMembershipUpsert = errors.New(\"membership upserts require all fields\")\n)\n\ntype (\n\t// clusterMetadataManagerImpl implements MetadataManager based on MetadataStore and Serializer\n\tclusterMetadataManagerImpl struct {\n\t\tserializer         serialization.Serializer\n\t\tpersistence        ClusterMetadataStore\n\t\tcurrentClusterName string\n\t\tlogger             log.Logger\n\t}\n)\n\nvar _ ClusterMetadataManager = (*clusterMetadataManagerImpl)(nil)\n\n// NewClusterMetadataManagerImpl returns new ClusterMetadataManager\nfunc NewClusterMetadataManagerImpl(\n\tpersistence ClusterMetadataStore,\n\tserializer serialization.Serializer,","sourceCodeStart":1,"sourceCodeEnd":36,"githubUrl":"https://github.com/temporalio/temporal/blob/bde624efd13fbd3843654058db6d9c716166318b/common/persistence/cluster_metadata_store.go#L1-L36","documentation":"ErrIncompleteMembershipUpsert is an exported sentinel in common/persistence/cluster_metadata_store.go, returned by UpsertClusterMembership when required fields of the membership record are missing. A membership upsert must contain complete identifying fields (host info etc.) for the record to be meaningful in the ring/membership table.","triggerScenarios":"Calling UpsertClusterMembership with a request missing required fields — e.g. empty HostID/HostAddress/Role or similar required members — so the store rejects it as incomplete.","commonSituations":"Membership broadcaster initialized before host identity is resolved; partially filled request structs in new code or tests; host info providers returning empty values during startup races.","solutions":["Populate all required fields of the upsert request before calling UpsertClusterMembership","Check errors.Is(err, persistence.ErrIncompleteMembershipUpsert) and log the request contents to find the missing field","Ensure host identity (address/ID) is resolved before starting membership broadcast loops"],"exampleFix":"// before\n_, err := store.UpsertClusterMembership(ctx, &persistence.UpsertClusterMembershipRequest{RecordExpiry: time.Minute})\n// after\n_, err := store.UpsertClusterMembership(ctx, &persistence.UpsertClusterMembershipRequest{\n    RecordExpiry: time.Minute,\n    HostID:       hostID,\n    HostAddress:  hostAddr,\n    Role:         role,\n})","handlingStrategy":"validation","validationCode":"func completeMembershipUpsert(req *persistence.UpsertClusterMembershipRequest) error {\n    if req.HostID == \"\" || req.HostAddress == \"\" || req.Role == \"\" {\n        return persistence.ErrIncompleteMembershipUpsert\n    }\n    return nil\n}","typeGuard":"func hasHostIdentity(h HostInfo) bool { return h.HostID != \"\" && h.HostAddress != \"\" }","tryCatchPattern":"_, err := manager.UpsertClusterMembership(ctx, req)\nif errors.Is(err, persistence.ErrIncompleteMembershipUpsert) {\n    logger.Error(\"incomplete membership upsert\", tag.Value(req))\n    return err\n}","preventionTips":["Resolve host identity before starting any membership broadcast loop","Use constructors that require all fields of the upsert request","Log the full request when this error occurs to spot the missing field quickly"],"tags":["persistence","cluster-membership","validation"],"backgroundTag":"missing-required-argument","analyzedSha":"bde624efd13fbd3843654058db6d9c716166318b","analyzedAt":"2026-09-01T07:18:39.080Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}