kubernetes/kops · error

serializing completed cluster spec: %w

Error message

serializing completed cluster spec: %w

What it means

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.

Source

Thrown at pkg/model/config.go:48

// ConfigBuilder populates the config store.
type ConfigBuilder struct {
	*KopsModelContext

	Lifecycle fi.Lifecycle
}

func (b *ConfigBuilder) Build(c *fi.CloudupModelBuilderContext) error {
	c.AddTask(&fitasks.ManagedFile{
		Name:      new(registry.PathKopsVersionUpdated),
		Lifecycle: b.Lifecycle,
		Base:      new(b.Cluster.Spec.ConfigStore.Base),
		Location:  new(registry.PathKopsVersionUpdated),
		Contents:  fi.NewStringResource(kopsbase.Version),
	})

	versionedYaml, err := kopscodecs.ToVersionedYamlWithVersion(b.Cluster, v1alpha2.SchemeGroupVersion)
	if err != nil {
		return fmt.Errorf("serializing completed cluster spec: %w", err)
	}
	c.AddTask(&fitasks.ManagedFile{
		Name:      new(registry.PathClusterCompleted),
		Lifecycle: b.Lifecycle,
		Base:      new(b.Cluster.Spec.ConfigStore.Base),
		Location:  new(registry.PathClusterCompleted),
		Contents:  fi.NewBytesResource(versionedYaml),
	})

	return nil
}

View on GitHub (pinned to 4c8573c808)

Solutions

1. Read the wrapped (%w) cause to identify the exact field that failed YAML serialization.
2. Run `kops get cluster -o yaml` and `kops replace` to round-trip the spec and surface invalid fields.
3. Ensure no unregistered/custom fields were injected into the cluster object (remove unknown keys from the spec).
4. If using a custom/patched kOps build, rebuild from upstream so codecs and schemes match.

Example fix

// before
// spec contains unknown top-level key: myCustomField: xyz
// after
// remove unknown fields:
kops get cluster -o yaml > cluster.yaml  # edit out unrecognized fields
kops replace -f cluster.yaml

if err := kopsapi.AddToScheme(scheme.Scheme); err != nil { return err }
if _, err := kopscodecs.ToVersionedYamlWithVersion(cluster, v1alpha2.SchemeGroupVersion); err != nil {
    return fmt.Errorf("cluster spec not serializable: %w", err)
}

func isSerializationError(err error) bool { return err != nil && strings.Contains(err.Error(), "serializing completed cluster spec") }

if err := b.Build(ctx, assetBuilder); err != nil {
    if isSerializationError(err) {
        log.Printf("serialization cause: %v", errors.Unwrap(err))
        // fix offending field in b.Cluster then retry
    }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• error marshaling yaml: %v
• error writing yaml to stdout: %v
• unable to marshal YAML: %v
• error parsing Cluster %q: %v
• unable to marshal YAML: %v

AI-assisted analysis of kubernetes/kops@4c8573c808 (2026-09-05). Data as JSON: /api/errors/7e8f2cbf568670fe. Report an issue: GitHub.