ahmetb/kubectx · error

cannot determine kubeconfig path

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.

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
• failed to change to namespace
• failed to close encoder for file
• failed to create transport
• failed to get current context

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

Appendix: 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)