ahmetb/kubectx · error

failed to parse kubeconfig: %w

Error message

failed to parse kubeconfig: %w

What it means

proxy.RewriteKubeconfig parses the input kubeconfig YAML bytes with client-go's clientcmd.Load before rewriting cluster/server entries. This error wraps any clientcmd parse/validation failure, including malformed YAML and kubeconfig data that fails clientcmd's structural validation (missing required fields).

Source

Thrown at internal/proxy/kubeconfig.go:19

package proxy

import (
	"fmt"

	"k8s.io/client-go/tools/clientcmd"
	clientcmdapi "k8s.io/client-go/tools/clientcmd/api"
)

// RewriteKubeconfig takes minified kubeconfig bytes and rewrites them so that:
//   - The cluster server URL points to the local proxy address (plain HTTP).
//   - insecure-skip-tls-verify is set (needed for plain HTTP).
//   - Certificate authority data is removed.
//   - User auth fields (client certs, tokens, exec, auth-provider) are removed
//     since the proxy handles authentication to the real API server.
func RewriteKubeconfig(data []byte, proxyAddr string) ([]byte, error) {
	cfg, err := clientcmd.Load(data)
	if err != nil {
		return nil, fmt.Errorf("failed to parse kubeconfig: %w", err)
	}

	for _, cluster := range cfg.Clusters {
		cluster.Server = "http://" + proxyAddr
		cluster.InsecureSkipTLSVerify = true
		cluster.CertificateAuthority = ""
		cluster.CertificateAuthorityData = nil
	}

	for name := range cfg.AuthInfos {
		cfg.AuthInfos[name] = &clientcmdapi.AuthInfo{}
	}

	// Rename contexts with [RO] suffix to indicate readonly mode.
	renames := make(map[string]string, len(cfg.Contexts))
	for name := range cfg.Contexts {
		renames[name] = name + "[RO]"
	}

View on GitHub (pinned to 12ad6fb22e)

Solutions

1. Validate the input independently first: kubectl --kubeconfig <file> config view (or clientcmd.Load in a scratch program) to see the parse error
2. Fix YAML syntax errors (tabs vs spaces, indentation) reported in the wrapped error
3. Ensure the bytes are a complete kubeconfig with apiVersion: v1, kind: Config and valid clusters/contexts/users sections
4. Confirm the source of the bytes (file path, HTTP response) actually contains the kubeconfig and not an error page or partial read

Example fix

// before
data, _ := execOut := os.ReadFile("cred.json")
proxy.RewriteKubeconfig(data, addr) // not a kubeconfig
// after
data, err := os.ReadFile("config")
if err != nil { return err }
out, err := proxy.RewriteKubeconfig(data, addr)

// Go
// Pre-validate the input bytes before RewriteKubeconfig
cfg, err := clientcmd.Load(data)
if err != nil {
    return fmt.Errorf("input is not a valid kubeconfig: %w", err)
}

out, err := proxy.RewriteKubeconfig(data, addr)
if err != nil {
    var uerr *url.Error
    if strings.Contains(err.Error(), "failed to parse kubeconfig") {
        return fmt.Errorf("check YAML syntax and required fields: %w", err)
    }
    return err
}

When it happens

Trigger: Calling RewriteKubeconfig with data that is not valid kubeconfig YAML/JSON, is empty, has wrong indentation, contains tabs, or lacks required fields (e.g. cluster without a server, context without cluster/user references).

Common situations: Reading a kubeconfig that was truncated or hand-edited; passing a regular kubeconfig of a different format (e.g. merged multi-doc file); passing an exec-credential JSON blob instead of a kubeconfig; encoding mix-ups (passing the wrong file's bytes).

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• kubeconfig error: %w
• kubeconfig error: %w
• failed to close encoder for file %d: %w
• failed to serialize kubeconfig: %w
• failed to load kubeconfig: %w

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