etcd version %q is not supported with etcd-manager, please s

Error message

etcd version %q is not supported with etcd-manager, please specify a supported version, remove the value to use the recommended version, or also set the image field to run a custom version

What it means

BuildOptions validates every etcd cluster's version against kOps' bundled etcd version list (currently 3.5.x/3.6.x/3.7.x minors). If the version is unsupported AND no custom image is set on the cluster, the build fails with this message, because etcd-manager has no bundled binaries for that version. Setting spec.etcdClusters[].image bypasses the check since the custom image supplies the binaries.

Source

Thrown at pkg/model/components/etcdmanager/options.go:76

		if etcdCluster.Backups == nil {
			etcdCluster.Backups = &kops.EtcdBackupSpec{}
		}
		if etcdCluster.Backups.BackupStore == "" {
			base := clusterSpec.ConfigStore.Base
			etcdCluster.Backups.BackupStore = join(base, "backups", "etcd", etcdCluster.Name)
		}

		if !etcdVersionIsSupported(etcdCluster.Version) {
			if etcdCluster.Image != "" {
				klog.Warningf("etcd version %q is not bundled by kOps and has not been tested; using binaries from custom image %q", etcdCluster.Version, etcdCluster.Image)
			} else {
				klog.Warningf("Unsupported etcd version %q detected; please update etcd version.", etcdCluster.Version)
				var versions []string
				for _, v := range etcdSupportedVersions() {
					versions = append(versions, v.Version)
				}
				klog.Warningf("Supported etcd versions: %s", strings.Join(versions, ", "))
				return fmt.Errorf("etcd version %q is not supported with etcd-manager, please specify a supported version, remove the value to use the recommended version, or also set the image field to run a custom version", etcdCluster.Version)
			}
		}
	}

	return nil
}

// etcdVersion describes how we want to support each etcd version.
type etcdVersion struct {
	Version          string
	Image            string
	SymlinkToVersion string
}

// etcdLatestImages lists the latest etcd patch image bundled by kops for each
// supported minor. All earlier patch versions within the same minor are
// generated as SymlinkToVersion entries by etcdSupportedVersions.
var etcdLatestImages = []etcdVersion{

View on GitHub (pinned to 4c8573c808)

Solutions

Remove the version field from the etcdCluster spec so kOps uses its recommended etcd version
Set version to a supported version listed in the accompanying klog warning (3.5.x/3.6.x/3.7.x)
Keep the unsupported version but set etcdClusters[].image to a container image containing those binaries (custom image path)
Run `kops upgrade cluster` / update kOps to get newer bundled etcd versions

Example fix

// before (cluster.yaml)
etcdClusters:
- name: main
  version: 3.4.13
  members: [...]
// after
etcdClusters:
- name: main
  members: [...]

Defensive patterns

Strategy: validation

Validate before calling

// Check etcd version against supported list before update
supported := []string{"3.5.x", "3.6.x", "3.7.x"} // see kops components.LatestEtcd*Version
for _, ec := range cluster.Spec.EtcdClusters {
    if ec.Version != "" && !versionIn(ec.Version, supported) && ec.Image == "" {
        return fmt.Errorf("etcd version %q unsupported and no image set", ec.Version)
    }
}

Try / catch

if err := applyClusterSpec(cluster); err != nil {
    if strings.Contains(err.Error(), "is not supported with etcd-manager") {
        return fmt.Errorf("pin a supported etcd version or set the image field: %w", err)
    }
    return err
}

Prevention

Omit the version field to let kOps pick the recommended etcd version
When pinning, choose versions from the klog "Supported etcd versions" list in the error output
For unlisted versions, always set etcdClusters[].image alongside version
Re-check etcd support matrix after every kOps upgrade

When it happens

Trigger: `kops update cluster` (or create cluster) where an etcdCluster has spec.etcdClusters[].version set to an unsupported string (e.g. "3.4.13", "3.8.0", or a typo like "3.5.1" misspelled) and etcdClusters[].image is empty.

Common situations: Clusters pinned to old etcd versions from pre-etcd-manager days, users trying to jump to a brand-new etcd release not yet bundled by kOps, or version typos in the cluster spec.

Related errors

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