{"record":{"id":"9796964f2da4b98a","repo":"kubernetes/kops","slug":"error-replacing-cluster-v","errorCode":null,"errorMessage":"error replacing cluster: %v","messagePattern":"error replacing cluster: (.+?)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/kops/replace.go","lineNumber":155,"sourceCode":"\t\t\t\t\t}\n\t\t\t\t\tif cluster == nil {\n\t\t\t\t\t\tif !c.Force {\n\t\t\t\t\t\t\treturn fmt.Errorf(\"cluster %v does not exist (try adding --force flag)\", clusterName)\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\terr = cloudup.PerformAssignments(v, vfsContext, cloud)\n\t\t\t\t\t\tif err != nil {\n\t\t\t\t\t\t\treturn fmt.Errorf(\"error populating configuration: %w\", err)\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\t_, err = clientset.CreateCluster(ctx, v)\n\t\t\t\t\t\tif err != nil {\n\t\t\t\t\t\t\treturn fmt.Errorf(\"error creating cluster: %v\", err)\n\t\t\t\t\t\t}\n\t\t\t\t\t} else {\n\t\t\t\t\t\t_, err = clientset.UpdateCluster(ctx, v, status)\n\t\t\t\t\t\tif err != nil {\n\t\t\t\t\t\t\treturn fmt.Errorf(\"error replacing cluster: %v\", err)\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\n\t\t\tcase *kopsapi.InstanceGroup:\n\t\t\t\tclusterName := v.ObjectMeta.Labels[kopsapi.LabelClusterName]\n\t\t\t\tif clusterName == \"\" {\n\t\t\t\t\treturn fmt.Errorf(\"must specify %q label with cluster name to replace instanceGroup\", kopsapi.LabelClusterName)\n\t\t\t\t}\n\t\t\t\tcluster, err := clientset.GetCluster(ctx, clusterName)\n\t\t\t\tif err != nil {\n\t\t\t\t\tif errors.IsNotFound(err) {\n\t\t\t\t\t\treturn fmt.Errorf(\"cluster %q not found\", clusterName)\n\t\t\t\t\t}\n\t\t\t\t\treturn fmt.Errorf(\"error fetching cluster %q: %v\", clusterName, err)\n\t\t\t\t}\n\t\t\t\t// check if the instancegroup exists already\n\t\t\t\tigName := v.ObjectMeta.Name","sourceCodeStart":137,"sourceCodeEnd":173,"githubUrl":"https://github.com/kubernetes/kops/blob/4c8573c808a73d578c5eadc86d410646ea0b0d73/cmd/kops/replace.go#L137-L173","documentation":"RunReplace wraps the failure of clientset.UpdateCluster when the replaced manifest is an existing cluster (cluster != nil). It fires when the state store rejects or errors on updating the cluster spec during `kops replace -f`; the underlying API/storage error is appended.","triggerScenarios":"UpdateCluster rejecting the change: spec field mutated that is immutable (e.g. changing zone/networking type on an existing cluster), state store write failure, concurrent modification conflict, or status fetch producing an incompatible object.","commonSituations":"Trying to change immutable fields (networking plugin, cluster name semantics) via replace; two operators running replace simultaneously; state-store permission/availability problems; apiVersion drift between manifest and stored cluster.","solutions":["Avoid changing immutable fields; use `kops edit cluster` + `kops update cluster` workflow or create a new cluster for incompatible changes","Re-run and check for a concurrent-modification conflict; serialize cluster changes within your team/tooling","Verify state store write access and health","Compare the manifest against the stored cluster (`kops get cluster <name> -o yaml`) and diff to find the rejected field","Read the wrapped error for the precise cause"],"exampleFix":"// before\nspec:\n  networking:\n    calico: {}   # changing from weave on an existing cluster via replace\n// after\n# keep existing networking or migrate via documented procedure\nkops replace -f cluster.yaml","handlingStrategy":"try-catch","validationCode":"// diff manifest against stored cluster to catch immutable changes early\nstored, err := clientset.GetCluster(ctx, v.Name)\nif err == nil && immutableFieldsChanged(stored, v) {\n    return fmt.Errorf(\"immutable fields changed (e.g. networking/zones); recreate cluster instead\")\n}","typeGuard":null,"tryCatchPattern":"_, err := clientset.UpdateCluster(ctx, v, status)\nif err != nil {\n    if isConflict(err) { /* serialize with other operators, retry */ }\n    return fmt.Errorf(\"update rejected: %w\", err)\n}","preventionTips":["Do not mutate immutable fields via replace; use the documented migration paths","Serialize cluster changes (lock or approval workflow)","Keep manifest apiVersion in sync with the stored cluster","Diff `kops get cluster <name> -o yaml` against your manifest before replace"],"tags":["cluster","state-store","update"],"backgroundTag":"immutable-field-update","analyzedSha":"4c8573c808a73d578c5eadc86d410646ea0b0d73","analyzedAt":"2026-09-05T04:13:19.212Z","contentChangedAt":"2026-09-05T04:13:19.212Z","schemaVersion":2},"datasetVersion":"2026-09-12T07:17:12.445Z"}