ahmetb/kubectx · error

kubeconfig file not found

Error message

kubeconfig file not found: %w

What it means

After Load skips all non-existent candidate paths, it checks whether any file was actually opened. If none were, it fails with this error carrying an os.ErrNotExist PathError constructed for the first candidate path. It means the loader found no kubeconfig at any of the configured locations.

Solutions

1. Create the kubeconfig: run a cluster bootstrap (minikube start / kind create cluster / kubeadm init) or copy a valid config to ~/.kube/config
2. Verify the path exists: ls -l $(echo $KUBECONFIG) and correct the KUBECONFIG value if wrong
3. If HOME changed (sudo, service user), point KUBECONFIG at the real config file explicitly
4. Check whether the file was deleted by a cleanup job and restore from backup

Example fix

// before
export KUBECONFIG=~/.kube/configs/prod.yaml  # file does not exist
// after
export KUBECONFIG=~/.kube/config  # or create the referenced file

// Go
p := os.Getenv("KUBECONFIG")
if p == "" { p = filepath.Join(os.Getenv("HOME"), ".kube", "config") }
if _, err := os.Stat(p); os.IsNotExist(err) {
    return fmt.Errorf("no kubeconfig at %s: create one with minikube/kind/kubectl config", p)
}

if err := run(); err != nil {
    if errors.Is(err, os.ErrNotExist) {
        return fmt.Errorf("kubeconfig missing — run 'minikube start' or set KUBECONFIG: %w", err)
    }
    return err
}

When it happens

Trigger: Calling Load when KUBECONFIG points only to non-existent paths, or KUBECONFIG is unset and $HOME/.kube/config does not exist (no cluster ever created, kubeadm/colima/minikube never initialized, fresh machine or CI container).

Common situations: Fresh developer machine or CI runner without a cluster config; KUBECONFIG set to a path that was deleted or never created; typo'd filename in KUBECONFIG (e.g. config.yml vs config.yaml); running under a different HOME than the one with the config.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• cannot determine kubeconfig path
• 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/399cc3c0c4e20454. Report an issue: GitHub.

Appendix: source

Thrown at internal/kubeconfig/kubeconfigloader.go:57

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
}

func (kf *kubeconfigFile) Reset() error {
	if err := kf.Truncate(0); err != nil {
		return fmt.Errorf("failed to truncate file: %w", err)
	}
	if _, err := kf.Seek(0, 0); err != nil {
		return fmt.Errorf("failed to seek in file: %w", err)
	}
	return nil
}

func kubeconfigPaths() ([]string, error) {
	// KUBECONFIG env var
	if v := os.Getenv("KUBECONFIG"); v != "" {

View on GitHub (pinned to 12ad6fb22e)