{"record":{"id":"7e8f2cbf568670fe","repo":"kubernetes/kops","slug":"serializing-completed-cluster-spec-w","errorCode":null,"errorMessage":"serializing completed cluster spec: %w","messagePattern":"serializing completed cluster spec: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/model/config.go","lineNumber":48,"sourceCode":"// ConfigBuilder populates the config store.\ntype ConfigBuilder struct {\n\t*KopsModelContext\n\n\tLifecycle fi.Lifecycle\n}\n\nfunc (b *ConfigBuilder) Build(c *fi.CloudupModelBuilderContext) error {\n\tc.AddTask(&fitasks.ManagedFile{\n\t\tName:      new(registry.PathKopsVersionUpdated),\n\t\tLifecycle: b.Lifecycle,\n\t\tBase:      new(b.Cluster.Spec.ConfigStore.Base),\n\t\tLocation:  new(registry.PathKopsVersionUpdated),\n\t\tContents:  fi.NewStringResource(kopsbase.Version),\n\t})\n\n\tversionedYaml, err := kopscodecs.ToVersionedYamlWithVersion(b.Cluster, v1alpha2.SchemeGroupVersion)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"serializing completed cluster spec: %w\", err)\n\t}\n\tc.AddTask(&fitasks.ManagedFile{\n\t\tName:      new(registry.PathClusterCompleted),\n\t\tLifecycle: b.Lifecycle,\n\t\tBase:      new(b.Cluster.Spec.ConfigStore.Base),\n\t\tLocation:  new(registry.PathClusterCompleted),\n\t\tContents:  fi.NewBytesResource(versionedYaml),\n\t})\n\n\treturn nil\n}\n","sourceCodeStart":30,"sourceCodeEnd":60,"githubUrl":"https://github.com/kubernetes/kops/blob/4c8573c808a73d578c5eadc86d410646ea0b0d73/pkg/model/config.go#L30-L60","documentation":"During the config builder's Build, kOps serializes the fully-populated cluster object to the v1alpha2 versioned YAML to store it as the 'completed' cluster spec in state storage. If ToVersionedYamlWithVersion fails (marshal/codec error), Build returns this wrapped error. It indicates the in-memory cluster spec could not be round-tripped through the API scheme.","triggerScenarios":"Running kops create/update where b.Cluster contains fields that cannot be serialized to v1alpha2 YAML — e.g. a field not registered in the scheme, an invalid nested value, or a codec/registry mismatch in a patched build.","commonSituations":"Cluster specs built with fields inconsistent with the target API version; custom builds of kOps with scheme registration problems; corrupted internal cluster objects after programmatic mutation.","solutions":["Read the wrapped (%w) cause to identify the exact field that failed YAML serialization.","Run `kops get cluster -o yaml` and `kops replace` to round-trip the spec and surface invalid fields.","Ensure no unregistered/custom fields were injected into the cluster object (remove unknown keys from the spec).","If using a custom/patched kOps build, rebuild from upstream so codecs and schemes match."],"exampleFix":"// before\n// spec contains unknown top-level key: myCustomField: xyz\n// after\n// remove unknown fields:\nkops get cluster -o yaml > cluster.yaml  # edit out unrecognized fields\nkops replace -f cluster.yaml","handlingStrategy":"validation","validationCode":"if err := kopsapi.AddToScheme(scheme.Scheme); err != nil { return err }\nif _, err := kopscodecs.ToVersionedYamlWithVersion(cluster, v1alpha2.SchemeGroupVersion); err != nil {\n    return fmt.Errorf(\"cluster spec not serializable: %w\", err)\n}","typeGuard":"func isSerializationError(err error) bool { return err != nil && strings.Contains(err.Error(), \"serializing completed cluster spec\") }","tryCatchPattern":"if err := b.Build(ctx, assetBuilder); err != nil {\n    if isSerializationError(err) {\n        log.Printf(\"serialization cause: %v\", errors.Unwrap(err))\n        // fix offending field in b.Cluster then retry\n    }\n}","preventionTips":["Only use fields registered in the kops API scheme; avoid injecting unknown keys.","Round-trip the spec (`kops get -o yaml` + `kops replace`) to catch unserializable fields early.","Keep kOps and its codecs at matching versions; avoid mixing custom patches."],"tags":["serialization","yaml","cluster-spec"],"backgroundTag":"cluster-spec-serialization-failed","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"}