ahmetb/kubectx · error

failed to load: %w

Error message

failed to load: %w

What it means

The loader (DefaultLoader, honoring KUBECONFIG or ~/.kube/config) failed to load any files: missing files where at least one is required, permission errors, or unset HOME making the default path underivable. This is the entry guard of Kubeconfig.Parse.

Source

Thrown at internal/kubeconfig/kubeconfig.go:74

func (k *Kubeconfig) WithLoader(l Loader) *Kubeconfig {
	k.loader = l
	return k
}

func (k *Kubeconfig) Close() error {
	var firstErr error
	for _, fe := range k.files {
		if err := fe.f.Close(); err != nil && firstErr == nil {
			firstErr = err
		}
	}
	return firstErr
}

func (k *Kubeconfig) Parse() error {
	rwcs, err := k.loader.Load()
	if err != nil {
		return fmt.Errorf("failed to load: %w", err)
	}

	k.files = make([]fileEntry, 0, len(rwcs))
	for i, f := range rwcs {
		var v yaml.Node
		if err := yaml.NewDecoder(f).Decode(&v); err != nil {
			// Close all file handles on failure to avoid leaks.
			for _, rf := range rwcs {
				rf.Close()
			}
			return fmt.Errorf("failed to decode file %d: %w", i, err)
		}
		rn := yaml.NewRNode(&v)
		if rn.YNode().Kind != yaml.MappingNode {
			for _, rf := range rwcs {
				rf.Close()
			}
			return fmt.Errorf("kubeconfig file %d is not a map document", i)

View on GitHub (pinned to 12ad6fb22e)

Solutions

1. Ensure KUBECONFIG paths exist and are readable (or unset the variable)
2. Set HOME to a valid directory so ~/.kube/config can be found
3. Check file permissions on the kubeconfig files

When it happens

Trigger: Thrown at internal/kubeconfig/kubeconfig.go:74 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/03cceee98ad639a6. Report an issue: GitHub.