GoogleContainerTools/skaffold · critical

unable to connect to Kubernetes: %w

Error message

unable to connect to Kubernetes: %w

What it means

The Kubernetes-cluster Job verifier preflight-checks that the target cluster is reachable before doing any work (loading images, creating jobs). `kubernetes.FailIfClusterIsNotReachable` failed, and the underlying connectivity error is wrapped with this message so the user knows the whole verify step cannot talk to the configured Kubernetes cluster.

Source

Thrown at pkg/skaffold/verify/k8sjob/verify.go:126

	v.localImages = images
}

func (v *Verifier) TrackBuildArtifacts(artifacts []graph.Artifact) {
	v.logger.RegisterArtifacts(artifacts)
}

// Verify executes specified artifacts by creating kubernetes Jobs for each image
// in the specified kubernetes cluster, executing them, and waiting for execution to complete.
func (v *Verifier) Verify(ctx context.Context, out io.Writer, allbuilds []graph.Artifact) error {
	var (
		childCtx context.Context
		endTrace func(...trace.SpanEndOption)
		wg       sync.WaitGroup
	)

	// TODO(aaron-prindle) add trace info
	if err := kubernetes.FailIfClusterIsNotReachable(v.kubectl.KubeContext); err != nil {
		return fmt.Errorf("unable to connect to Kubernetes: %w", err)
	}

	childCtx, endTrace = instrumentation.StartTrace(ctx, "Verify_LoadImages")
	if err := v.imageLoader.LoadImages(childCtx, out, v.localImages, v.localImages, v.localImages); err != nil {
		endTrace(instrumentation.TraceEndError(err))
		return err
	}
	endTrace()

	builds := []graph.Artifact{}
	const maxWorkers = math.MaxInt64
	s := semgroup.NewGroup(context.Background(), maxWorkers)

	for _, tc := range v.cfg {
		foundArtifact := false
		nTC := *tc

		for _, b := range allbuilds {

View on GitHub (pinned to a1189de023)

Solutions

  1. Verify connectivity: `kubectl --context <ctx> cluster-info` and fix kubeconfig/credentials
  2. Check KUBECONFIG points at the right file and the context/cluster/server URL is correct
  3. Reconnect VPN / fix network access to the API server endpoint
  4. Re-authenticate (e.g. `aws eks update-kubeconfig`, `gcloud container clusters get-credentials`)
  5. Confirm the cluster is actually running and not paused/deleted

Example fix

// before
skaffold verify --kube-context stale-context   # unable to connect
// after
kubectl config use-context my-cluster
aws eks update-kubeconfig --name my-cluster
skaffold verify
Defensive patterns

Strategy: validation

Validate before calling

// preflight before skaffold verify
import "k8s.io/client-go/tools/clientcmd"
func clusterReachable(kubeContext string) error {
    cfg, err := clientcmd.NewNonInteractiveDeferredLoadingClientConfig(
        clientcmd.NewDefaultClientConfigLoadingRules(),
        &clientcmd.ConfigOverrides{CurrentContext: kubeContext}).ClientConfig()
    if err != nil { return err }
    return clientset.NewForConfigOrDie(cfg).Discovery().ServerVersion()
}

Type guard

func contextExists(kubeContext string) bool {
    cfg, _ := clientcmd.NewNonInteractiveDeferredLoadingClientConfig(
        clientcmd.NewDefaultClientConfigLoadingRules(), nil).RawConfig()
    _, ok := cfg.Contexts[kubeContext]
    return ok
}

Try / catch

if err := verifier.Verify(ctx, out); err != nil {
    if strings.Contains(err.Error(), "unable to connect to Kubernetes") {
        // surface `kubectl cluster-info` guidance to the user
    }
}

Prevention

When it happens

Trigger: Calling Verify (pkg/skaffold/verify/k8sjob) with a kubeContext whose API server is unreachable: wrong kubeconfig context, cluster down, no network/VPN, expired credentials, or a misconfigured `--kube-context` / kubectl context in skaffold.yaml.

Common situations: Developer switched kubectl contexts and forgot; remote cluster endpoint changed (EKS/GKE token or IP rot); VPN disconnected; KUBECONFIG env var pointing at a stale file; apiserver temporarily down during maintenance.

Related errors

AI-assisted analysis of GoogleContainerTools/skaffold@a1189de023 (2026-09-05). Data as JSON: /api/errors/c4d0f8012758eaff. Report an issue: GitHub.