ahmetb/kubectx · error

kubectl is required for --shell but was not found in PATH

Error message

kubectl is required for --shell but was not found in PATH

What it means

Validation guard in resolveKubectl: neither the KUBECTL environment variable nor the kubectl binary in PATH could be found. The --shell feature shells out to kubectl config view to build an isolated kubeconfig, so it aborts before doing anything when kubectl is unavailable.

Source

Thrown at cmd/kubectx/shell.go:55

		printEntry: func(w io.Writer, ctxName string) {
			fmt.Fprintf(w, "%s kubectl context is %s in this shell — type 'exit' to leave.\n",
				badgeColor.Sprint("[ISOLATED SHELL]"), printer.WarningColor.Sprint(ctxName))
		},
		printExit: func(w io.Writer, prevCtx string) {
			fmt.Fprintf(w, "%s kubectl context is now %s.\n",
				badgeColor.Sprint("[ISOLATED SHELL EXITED]"), printer.WarningColor.Sprint(prevCtx))
		},
	}
	return s.run(stderr)
}

func resolveKubectl() (string, error) {
	if v := os.Getenv("KUBECTL"); v != "" {
		return v, nil
	}
	path, err := exec.LookPath("kubectl")
	if err != nil {
		return "", fmt.Errorf("kubectl is required for --shell but was not found in PATH")
	}
	return path, nil
}

func extractMinimalKubeconfig(kubectlPath, contextName string) ([]byte, error) {
	cmd := exec.Command(kubectlPath, "config", "view", "--minify", "--flatten",
		"--context", contextName)
	cmd.Env = os.Environ()
	data, err := cmd.Output()
	if err != nil {
		return nil, fmt.Errorf("kubectl config view failed: %w", err)
	}
	return data, nil
}

func detectShell() string {
	if runtime.GOOS == "windows" {
		// cmd.exe always sets the PROMPT env var, so if it is present

View on GitHub (pinned to 12ad6fb22e)

Solutions

1. Install kubectl and ensure it is on PATH (verify with kubectl version --client)
2. Alternatively set KUBECTL to the absolute path of a kubectl binary
3. If kubectl is installed but not found, fix PATH in your shell profile

When it happens

Trigger: Thrown at cmd/kubectx/shell.go:55 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of ahmetb/kubectx@12ad6fb22e (2026-09-02). Data as JSON: /api/errors/d208912359bccd5d. Report an issue: GitHub.