kubernetes/kops · error

api-version must be specified

Error message

api-version must be specified

What it means

The helper must emit an ExecCredential with a concrete client.authentication.k8s.io apiVersion (v1alpha1 or v1beta1). If options.APIVersion is empty, the switch in RunKubectlAuthHelper returns this error because kubectl requires a known schema version to parse the output. Normally InitDefaults() sets v1beta1, so the empty value only occurs when defaults were skipped or explicitly cleared.

Source

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

	cmd.Flags().StringVar(&options.ClusterName, "cluster", options.ClusterName, "cluster to target")
	cmd.Flags().DurationVar(&options.Lifetime, "lifetime", options.Lifetime, "lifetime of the credential to issue")

	return cmd
}

// RunKubectlAuthHelper implements the kubectl auth helper, which creates an authentication token
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")

View on GitHub (pinned to 4c8573c808)

Solutions

1. Call options.InitDefaults() before running, or pass --api-version v1beta1 explicitly.
2. If Go code bypasses NewCmdHelperKubectlAuth, initialize APIVersion to "v1beta1" (or "v1alpha1") yourself.
3. Fix shell quoting so an empty $VAR doesn't result in an empty flag value.

Example fix

// before
options := &helpers.HelperKubectlAuthOptions{}
err := helpers.RunKubectlAuthHelper(ctx, f, out, options)
// after
options := &helpers.HelperKubectlAuthOptions{}
options.InitDefaults()
err := helpers.RunKubectlAuthHelper(ctx, f, out, options)

opts := &helpers.HelperKubectlAuthOptions{}
opts.InitDefaults() // sets APIVersion to v1beta1
if opts.APIVersion == "" {
    opts.APIVersion = "v1beta1"
}

When it happens

Trigger: Calling RunKubectlAuthHelper with an options struct that never had InitDefaults() called and APIVersion unset (empty string), or a flag wiring bug that passes --api-version "".

Common situations: Constructing HelperKubectlAuthOptions directly in Go without calling InitDefaults; a wrapper script that sets --api-version to an empty variable; refactoring the cobra command away from the default-initialization path.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• ClusterName is required
• api-version %q is not supported
• DIGITALOCEAN_ACCESS_TOKEN is required
• DIGITALOCEAN_ACCESS_TOKEN is required
• failed to parse apiVersion %q

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