{"record":{"id":"93aad8ea93f3c1b0","repo":"temporalio/temporal","slug":"version-increment-0-or-2147483647","errorCode":null,"errorMessage":"Version increment <= 0 or > 2147483647","messagePattern":"Version increment <= 0 or > 2147483647","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"common/cluster/metadata.go","lineNumber":152,"sourceCode":"\nfunc NewMetadata(\n\tenableGlobalNamespace bool,\n\tfailoverVersionIncrement int64,\n\tmasterClusterName string,\n\tcurrentClusterName string,\n\tclusterInfo map[string]ClusterInformation,\n\tclusterMetadataStore persistence.ClusterMetadataManager,\n\trefreshDuration dynamicconfig.DurationPropertyFn,\n\tlogger log.Logger,\n) Metadata {\n\tif len(clusterInfo) == 0 {\n\t\tpanic(\"Empty cluster information\")\n\t} else if len(masterClusterName) == 0 {\n\t\tpanic(\"Master cluster name is empty\")\n\t} else if len(currentClusterName) == 0 {\n\t\tpanic(\"Current cluster name is empty\")\n\t} else if failoverVersionIncrement == 0 || failoverVersionIncrement > math.MaxInt32 {\n\t\tpanic(\"Version increment <= 0 or > 2147483647\")\n\t}\n\n\tversionToClusterName, err := updateVersionToClusterName(clusterInfo, failoverVersionIncrement)\n\tif err != nil {\n\t\t// nolint:forbidigo // matches the other startup-config panics in this constructor\n\t\tpanic(err.Error())\n\t}\n\tif _, ok := clusterInfo[currentClusterName]; !ok {\n\t\tpanic(\"Current cluster is not specified in cluster info\")\n\t}\n\tif _, ok := clusterInfo[masterClusterName]; !ok {\n\t\tpanic(\"Master cluster is not specified in cluster info\")\n\t}\n\n\tcopyClusterInfo := make(map[string]ClusterInformation)\n\tmaps.Copy(copyClusterInfo, clusterInfo)\n\tif refreshDuration == nil {\n\t\trefreshDuration = dynamicconfig.GetDurationPropertyFn(refreshInterval)","sourceCodeStart":134,"sourceCodeEnd":170,"githubUrl":"https://github.com/temporalio/temporal/blob/bde624efd13fbd3843654058db6d9c716166318b/common/cluster/metadata.go#L134-L170","documentation":"NewMetadata panics when failoverVersionIncrement is 0 or greater than math.MaxInt32 (2147483647). The failover version increment is used as a modulus/spacing factor to allocate non-overlapping failover version ranges per cluster, so it must be a positive 32-bit integer. Passing an invalid increment makes version arithmetic (GetNextFailoverVersion, ClusterNameForFailoverVersion) incorrect, hence the fail-fast panic.","triggerScenarios":"cluster.NewMetadata(..., failoverVersionIncrement=0, ...) or an increment larger than math.MaxInt32; typically a zero-valued struct or misread int64 config field passed directly.","commonSituations":"Config where failoverVersionIncrement was never set (defaults to 0), copying sample multi-cluster configs and changing the increment to a value like 4294967296, or tests constructing metadata manually with an unset parameter.","solutions":["Pass a valid positive increment (conventionally 1 for single cluster, or distinct small positive values per cluster setup), e.g. cluster.NewMetadata(clusterInfo, \"master\", \"current\", 1, nil, nil)","Validate the config value in Go with an int32 cast before constructing metadata","Use NewMetadataFromConfig so the increment is read from validated config defaults"],"exampleFix":"// before\nmd := cluster.NewMetadata(clusterInfo, \"master\", \"current\", 0, nil, nil)\n// after\nmd := cluster.NewMetadata(clusterInfo, \"master\", \"current\", 1, nil, nil)","handlingStrategy":"validation","validationCode":"if failoverVersionIncrement <= 0 || failoverVersionIncrement > math.MaxInt32 {\n  return fmt.Errorf(\"failoverVersionIncrement must be in (0, %d], got %d\", math.MaxInt32, failoverVersionIncrement)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Derive the increment from validated config rather than ad-hoc literals","Keep per-cluster increments small and distinct (e.g. 1, 2, 3...)","Add a startup self-check that constructs metadata and converts any panic into a fatal config error message"],"tags":["go","panic","configuration","failover-version"],"backgroundTag":"invalid-config-value","analyzedSha":"bde624efd13fbd3843654058db6d9c716166318b","analyzedAt":"2026-09-01T07:18:39.080Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}