tailscale/tailscale · error · errInvalidKubeconfig

invalid kubeconfig

Error message

invalid kubeconfig

What it means

updateKubeconfig unmarshals your existing kubeconfig YAML with yaml.Unmarshal; if parsing fails it returns the sentinel errInvalidKubeconfig. The command rewrites kubeconfig entries to point at the tailnet FQDN, so it must first load the current file found via kubeconfigPath() (honoring KUBECONFIG). Note the sentinel discards the yaml error detail, so the exact syntax problem is not shown.

Source

Thrown at cmd/tailscale/cli/configure-kube.go:215

}

// appendOrSetNamed finds a map with a "name" key matching name in dst, and
// replaces it with val. If no such map is found, val is appended to dst.
func appendOrSetNamed(dst []any, name string, val map[string]any) []any {
	if got := slices.IndexFunc(dst, func(m any) bool {
		if m, ok := m.(map[string]any); ok {
			return m["name"] == name
		}
		return false
	}); got != -1 {
		dst[got] = val
	} else {
		dst = append(dst, val)
	}
	return dst
}

var errInvalidKubeconfig = errors.New("invalid kubeconfig")

func updateKubeconfig(cfgYaml []byte, scheme, fqdn string) ([]byte, error) {
	var cfg map[string]any
	if len(cfgYaml) > 0 {
		if err := yaml.Unmarshal(cfgYaml, &cfg); err != nil {
			return nil, errInvalidKubeconfig
		}
	}
	if cfg == nil {
		cfg = map[string]any{
			"apiVersion": "v1",
			"kind":       "Config",
		}
	} else if cfg["apiVersion"] != "v1" || cfg["kind"] != "Config" {
		return nil, errInvalidKubeconfig
	}

	var clusters []any

View on GitHub (pinned to cfe32b8be6)

Solutions

1. Validate the file: `yq -e '.' "$KUBECONFIG"` or `kubectl config view --raw` to locate the syntax error
2. Fix or remove the malformed file, keeping a backup first
3. Point KUBECONFIG at a known-good file, or unset it so the default path is used, then re-run `tailscale configure kube`

Example fix

# before
$ tailscale configure kube apiserver
error: invalid kubeconfig

# after (find and fix the YAML, then retry)
$ yq -e '.' "$HOME/.kube/config"   # reports the exact parse problem
$ cp ~/.kube/config ~/.kube/config.bak
$ tailscale configure kube apiserver

KUBECONFIG="${KUBECONFIG:-$HOME/.kube/config}"
if [ -s "$KUBECONFIG" ] && ! yq -e '.' "$KUBECONFIG" >/dev/null 2>&1; then
  echo "invalid YAML in $KUBECONFIG; fix or back it up first"; exit 1
fi
tailscale configure kube "$APISERVER"

var cfg map[string]any
if err := yaml.Unmarshal(cfgYaml, &cfg); err != nil {
    return fmt.Errorf("kubeconfig at %s is malformed: %w", path, err) // keep parse detail
}

When it happens

Trigger: The file that kubeconfigPath() resolves (usually $KUBECONFIG or ~/.kube/config) exists but is not valid YAML — tabs used for indentation, truncated file, merge of conflicting snippets, or binary/garbage content.

Common situations: Hand-edited kubeconfig with a typo; multiple KUBECONFIG entries where one file is corrupt; a partially-written file after an interrupted kubectl operation; templating artifacts left in the YAML.

Related errors

• Tailscale is not running
• failed to initialize helm action configuration: %w
• error getting rest config: %w
• error creating Kubernetes clientset: %w
• too many collisions generating new session; please refresh p

AI-assisted analysis of tailscale/tailscale@cfe32b8be6 (2026-08-15). Data as JSON: /api/errors/d2c69d322655ad04. Report an issue: GitHub.