kubernetes/kops · error

api-version %q is not supported

Error message

api-version %q is not supported

What it means

Only client.authentication.k8s.io v1alpha1 and v1beta1 are accepted by this helper; any other --api-version value hits the default branch and returns this error. kOps validates strictly rather than passing the version through, because the emitted ExecCredential.apiVersion must match a schema kubectl understands.

Source

Thrown at pkg/commands/helpers/kubectl_auth.go:109

func RunKubectlAuthHelper(ctx context.Context, f *util.Factory, out io.Writer, options *HelperKubectlAuthOptions) error {
	if options.ClusterName == "" {
		return fmt.Errorf("ClusterName is required")
	}

	execCredential := &ExecCredential{
		Kind: "ExecCredential",
	}

	switch options.APIVersion {
	case "":
		return fmt.Errorf("api-version must be specified")
	case "v1alpha1":
		execCredential.APIVersion = "client.authentication.k8s.io/v1alpha1"
	case "v1beta1":
		execCredential.APIVersion = "client.authentication.k8s.io/v1beta1"

	default:
		return fmt.Errorf("api-version %q is not supported", options.APIVersion)
	}

	cacheFilePath := cacheFilePath(f.KopsStateStore(), options.ClusterName)
	cached, err := loadCachedExecCredential(cacheFilePath)
	if err != nil {
		klog.Infof("cached credential %q was not valid: %v", cacheFilePath, err)
		cached = nil
	}

	if cached != nil && cached.APIVersion != execCredential.APIVersion {
		klog.Infof("cached credential had wrong api version")
		cached = nil
	}

	isCached := false
	if cached != nil {
		execCredential = cached
		isCached = true

View on GitHub (pinned to 4c8573c808)

Solutions

1. Use --api-version v1beta1 (the default) or v1alpha1.
2. Upgrade kOps to a version that supports the apiVersion your kubectl requests, or pin kubectl's exec plugin version via user.exec in the kubeconfig.
3. Check kubectl's client.authentication.k8s.io requested version and match it exactly to v1alpha1 or v1beta1.

Example fix

// before
args: ["helpers", "kubectl-auth", "--api-version", "v1"]
// after
args: ["helpers", "kubectl-auth", "--api-version", "v1beta1"]

func validAPIVersion(v string) bool {
    return v == "v1alpha1" || v == "v1beta1"
}
if !validAPIVersion(opts.APIVersion) {
    return fmt.Errorf("unsupported api-version %q; use v1alpha1 or v1beta1", opts.APIVersion)
}

When it happens

Trigger: Passing --api-version with a value like v1, v1beta2, or client.authentication.k8s.io/v1beta1 to kubectl-auth, or setting options.APIVersion to any string other than "v1alpha1"/"v1beta1" before calling RunKubectlAuthHelper.

Common situations: Newer kubectl versions requesting client.authentication.k8s.io/v1 (not supported by this kOps version); guessing flag values from kubectl docs rather than kOps docs; copying an apiVersion string including the group prefix.

Related errors

• failed to parse apiVersion %q
• at least one channel URL is required
• spec.PublicKey is required
• unable to execute --dry-run without setting --output
• --name is required

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