kubernetes/kops · error

unknown phase %q, available phases: %s

Error message

unknown phase %q, available phases: %s

What it means

`kops update cluster --phase` restricts the update to a single phase. RunUpdateCluster validates the value against the known cloudup phases (network, security/iam, cluster); anything else, including typos and unknown aliases, triggers this error listing the valid phases.

Source

Thrown at cmd/kops/update_cluster.go:318

		err = sshCredentialStore.AddSSHPublicKey(ctx, authorized)
		if err != nil {
			return results, fmt.Errorf("error adding SSH public key: %v", err)
		}

		klog.Infof("Using SSH public key: %v\n", c.SSHPublicKey)
	}

	var phase cloudup.Phase
	if c.Phase != "" {
		switch strings.ToLower(c.Phase) {
		case string(cloudup.PhaseNetwork):
			phase = cloudup.PhaseNetwork
		case string(cloudup.PhaseSecurity), "iam": // keeping IAM for backwards compatibility
			phase = cloudup.PhaseSecurity
		case string(cloudup.PhaseCluster):
			phase = cloudup.PhaseCluster
		default:
			return results, fmt.Errorf("unknown phase %q, available phases: %s", c.Phase, strings.Join(cloudup.Phases.List(), ","))
		}
	}

	deletionProcessing := fi.DeletionProcessingModeDeleteIfNotDeferrred
	if c.Prune {
		deletionProcessing = fi.DeletionProcessingModeDeleteIncludingDeferred
	}

	lifecycleOverrideMap := make(map[string]fi.Lifecycle)

	for _, override := range c.LifecycleOverrides {
		values := strings.Split(override, "=")
		if len(values) != 2 {
			return results, fmt.Errorf("incorrect syntax for lifecyle-overrides, correct syntax is TaskName=lifecycleName, override provided: %q", override)
		}

		taskName := values[0]
		lifecycleName := values[1]

View on GitHub (pinned to 4c8573c808)

Solutions

1. Use one of the listed phases: network, security (or iam), cluster
2. Fix capitalization — phase strings are lowercase
3. Split multi-phase work into sequential invocations (network, then security, then cluster) instead of inventing a phase name
4. Run `kops update cluster --help` to see the phases supported by your kOps version

Example fix

// before
kops update cluster c.k8s.local --phase Infrastructure --yes
// after
kops update cluster c.k8s.local --phase network --yes
kops update cluster c.k8s.local --phase security --yes

valid := map[string]bool{"network": true, "security": true, "iam": true, "cluster": true, "": true}
if !valid[c.Phase] {
	return fmt.Errorf("--phase %q invalid; use network|security|iam|cluster", c.Phase)
}
_ = runUpdateCluster(c)

When it happens

Trigger: `kops update cluster --phase <value>` where <value> is not one of: "network", "security", "iam" (legacy alias), or "cluster" — e.g. --phase infrastructure, --phase Network (wrong case), or an empty/mistyped value.

Common situations: Copy-pasting phase names from old kOps docs or other tools; capitalization mismatch; assuming phases like 'validate' or 'dns' are selectable; scripts written for kOps versions with different phase sets.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• unsupported output type %q
• --project cannot be empty; specify a project or omit the fla
• cannot specify --key with "all"
• cannot specify --primary with "all"
• --name is required

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