ahmetb/kubectx · error

cannot determine kubeconfig path: %w

Error message

cannot determine kubeconfig path: %w

What it means

StandardKubeconfigLoader.Load resolves which kubeconfig files to open by calling kubeconfigPaths(), which uses the KUBECONFIG env var or falls back to $HOME/.kube/config. This error wraps a failure of that resolution — currently the only cause is the "HOME or USERPROFILE environment variable not set" error returned when no home directory can be determined.

Source

Thrown at internal/kubeconfig/kubeconfigloader.go:42

)

var (
	DefaultLoader Loader = new(StandardKubeconfigLoader)
)

type StandardKubeconfigLoader struct{}

type kubeconfigFile struct {
	*os.File
	path string
}

func (kf *kubeconfigFile) Path() string { return kf.path }

func (*StandardKubeconfigLoader) Load() ([]ReadWriteResetCloser, error) {
	paths, err := kubeconfigPaths()
	if err != nil {
		return nil, fmt.Errorf("cannot determine kubeconfig path: %w", err)
	}

	var files []ReadWriteResetCloser
	for _, p := range paths {
		f, err := os.OpenFile(p, os.O_RDWR, 0)
		if err != nil {
			if os.IsNotExist(err) {
				continue
			}
			return nil, fmt.Errorf("failed to open file %q: %w", p, err)
		}
		files = append(files, &kubeconfigFile{File: f, path: p})
	}
	if len(files) == 0 {
		return nil, fmt.Errorf("kubeconfig file not found: %w",
			&os.PathError{Op: "open", Path: paths[0], Err: os.ErrNotExist})
	}
	return files, nil

View on GitHub (pinned to 12ad6fb22e)

Solutions

1. Set the KUBECONFIG environment variable to the kubeconfig path(s): export KUBECONFIG=/path/to/config
2. Set HOME to the user's home directory: export HOME=/home/user (or USERPROFILE on Windows)
3. If running as a service/container, set HOME in the unit file / Dockerfile (ENV HOME=/root)
4. Check that the process runs as the intended user, not one lacking a home

Example fix

// before
exec.Command("kubectl-ctx", "list") // HOME unset in service
// after
cmd := exec.Command("kubectl-ctx", "list")
cmd.Env = append(os.Environ(), "HOME=/home/user")

// Go
if os.Getenv("KUBECONFIG") == "" && os.Getenv("HOME") == "" && os.Getenv("USERPROFILE") == "" {
    return errors.New("set KUBECONFIG or HOME before loading kubeconfig")
}

files, err := loader.Load()
if err != nil && strings.Contains(err.Error(), "cannot determine kubeconfig path") {
    return fmt.Errorf("environment incomplete: %w (set KUBECONFIG or HOME)", err)
}

When it happens

Trigger: Calling Load (or anything that loads a kubeconfig: Kubeconfig construction, switchNamespace, clearContext, etc.) when the KUBECONFIG env var is unset AND cmdutil.HomeDir() returns an empty string (neither HOME nor USERPROFILE set, and no drop-in home-dir helper applies).

Common situations: Running in a container or daemon (systemd service, CI job, cron, Docker ENTRYPOINT) where HOME is not set; running as a user with no passwd entry; misconfigured su/sudo environment stripping HOME.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• kubeconfig file not found: %w
• kubeconfig error: %w
• failed to get current context: %w
• failed to read namespace of "%s": %w
• kubeconfig error: %w

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