kubernetes/kops · error

unknown phase %q

Error message

unknown phase %q

What it means

Run() switches on c.Phase to determine which lifecycles apply; the default branch rejects any Phase value that is not one of the recognized phases (e.g. Apply, Plan, or specific lifecycle phases). The user supplied an invalid --phase value, so Run aborts before doing any work.

Source

Thrown at upup/pkg/fi/cloudup/apply_cluster.go:244

	case PhaseNetwork:
		securityLifecycle = fi.LifecycleIgnore
		clusterLifecycle = fi.LifecycleIgnore

	case PhaseSecurity:
		networkLifecycle = fi.LifecycleExistsAndWarnIfChanges
		clusterLifecycle = fi.LifecycleIgnore

	case PhaseCluster:
		if c.TargetName == TargetDryRun {
			securityLifecycle = fi.LifecycleExistsAndWarnIfChanges
			networkLifecycle = fi.LifecycleExistsAndWarnIfChanges
		} else {
			networkLifecycle = fi.LifecycleExistsAndValidates
			securityLifecycle = fi.LifecycleExistsAndValidates
		}

	default:
		return nil, fmt.Errorf("unknown phase %q", c.Phase)
	}

	assetBuilder := assets.NewAssetBuilder(c.Clientset.VFSContext(), c.Cluster.Spec.Assets, c.GetAssets)
	// Use HasSuffix for CI builds where the cluster spec contains a GCS url like
	// https://storage.googleapis.com/k8s-release-dev/ci/v1.36.0-alpha.0.615+cc55e3447816e4
	// and ControlPlaneRunningVersion is a build like v1.36.0-alpha.0.615+cc55e3447816e4
	// Release versions will be an exact match
	if len(c.ControlPlaneRunningVersion) > 0 && !strings.HasSuffix(c.Cluster.Spec.KubernetesVersion, c.ControlPlaneRunningVersion) {
		assetBuilder.KubeletSupportedVersion = c.ControlPlaneRunningVersion
	}
	err = c.upgradeSpecs(ctx, assetBuilder)
	if err != nil {
		return nil, err
	}

	err = c.validateKopsVersion()
	if err != nil {
		return nil, err

View on GitHub (pinned to 4c8573c808)

Solutions

1. Rerun with a valid --phase value (run 'kops update cluster --help' to list phases); phase names are case-sensitive.
2. Omit --phase entirely to run the full apply.
3. If a script hardcodes an old phase name, update it to the phase name supported by the installed kops version.

Example fix

// before
Options.Phase = "masters"
// after
Options.Phase = fi.LifecyclePhase("ControlPlane")

var validPhases = map[string]bool{"": true, "Cluster": true, "Network": true, "Security": true, "ControlPlane": true, "Node": true, "Additional": true}
if !validPhases[string(opts.Phase)] {
    return fmt.Errorf("unsupported phase %q", opts.Phase)
}

When it happens

Trigger: kops update cluster --phase=bogus (or Phase set programmatically on UpdateClusterOptions) with a string that does not exactly match a supported phase constant such as Cluster, Network, Security, ControlPlane, Node, or the empty string for full apply.

Common situations: Typo in --phase (e.g. 'master' instead of 'ControlPlane', lowercase names); scripts carrying a phase name from an older kops version where phases were renamed; CI configs passing an empty or whitespace value.

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

• at least one channel URL is required
• spec.PublicKey is required
• unable to execute --dry-run without setting --output
• --name is required
• --azure-subscription-id is required

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