ahmetb/kubectx · error

kubeconfig file %d is not a map document

Error message

kubeconfig file %d is not a map document

What it means

Validation guard in Parse: the i-th kubeconfig file decoded to valid YAML but its root node is not a mapping (e.g. the file contains a bare scalar, a list, or only comments). Handles are closed and the file index is reported.

Source

Thrown at internal/kubeconfig/kubeconfig.go:92

		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)
		}
		var p string
		if ph, ok := f.(PathHinter); ok {
			p = ph.Path()
		}
		k.files = append(k.files, fileEntry{f: f, path: p, config: rn})
	}
	return nil
}

// ConfigPaths returns the file paths of all loaded kubeconfig files.
// Returns nil if the kubeconfig was not loaded from files (e.g. in tests).
func (k *Kubeconfig) ConfigPaths() []string {
	var paths []string
	for _, fe := range k.files {
		if fe.path != "" {
			paths = append(paths, fe.path)
		}

View on GitHub (pinned to 12ad6fb22e)

Solutions

1. Open the N-th KUBECONFIG file and ensure the document is a YAML mapping with apiVersion/kind/contexts style keys
2. Remove files that contain stray non-document content
3. Restore from backup or regenerate the file

When it happens

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