GoogleContainerTools/skaffold · critical

unable to connect to Kubernetes: %w

Error message

unable to connect to Kubernetes: %w

What it means

Before deploying, the kubectl deployer proactively checks cluster reachability via kubernetes.FailIfClusterIsNotReachable to produce a clearer message than a failed apply. If the API server cannot be contacted (DNS, network, auth, or kubeconfig issues), the underlying error is wrapped as 'unable to connect to Kubernetes'.

Source

Thrown at pkg/skaffold/deploy/kubectl/kubectl.go:211

// Deploy templates the provided manifests with a simple `find and replace` and
// runs `kubectl apply` on those manifests
func (k *Deployer) Deploy(ctx context.Context, out io.Writer, builds []graph.Artifact, manifestsByConfig manifest.ManifestListByConfig) error {
	manifests := manifestsByConfig.GetForConfig(k.ConfigName())
	var (
		err      error
		childCtx context.Context
		endTrace func(...trace.SpanEndOption)
	)
	instrumentation.AddAttributesToCurrentSpanFromContext(ctx, map[string]string{
		"DeployerType": "kubectl",
	})

	// Check that the cluster is reachable.
	// This gives a better error message when the cluster can't
	// be reached.
	if err := kubernetes.FailIfClusterIsNotReachable(k.kubectl.KubeContext); err != nil {
		return fmt.Errorf("unable to connect to Kubernetes: %w", err)
	}

	// if any hydrated manifests are passed to `skaffold apply`, only deploy these
	// also, manually set the labels to ensure the runID is added
	if len(k.hydratedManifests) > 0 {
		_, endTrace = instrumentation.StartTrace(ctx, "Deploy_readHydratedManifests")
		manifests, err = k.kubectl.ReadManifests(ctx, k.hydratedManifests)
		if err != nil {
			endTrace(instrumentation.TraceEndError(err))
			return err
		}
		manifests, err = manifests.SetLabels(k.labeller.Labels(), manifest.NewResourceSelectorLabels(k.transformableAllowlist, k.transformableDenylist))
		endTrace()
	}

	if err != nil {
		return err
	}

View on GitHub (pinned to a1189de023)

Solutions

1. Verify with `kubectl cluster-info` (same context) and start the cluster/VPN if unreachable.
2. Check the current context: `kubectl config current-context`, and switch/correct it or the KUBECONFIG path.
3. Re-authenticate (gcloud/aws/az credentials) if the probe error indicates auth.
4. For minikube/kind: `minikube start` or `kind create cluster` before deploying.

Example fix

// before
$ skaffold deploy
unable to connect to Kubernetes: ... dial tcp: lookup nonexistent.cluster
// after
kubectl config use-context my-cluster
kubectl cluster-info
$ skaffold deploy

// Preflight: cluster must be reachable before invoking deploy
if err := exec.Command("kubectl", "cluster-info").Run(); err != nil {
    return fmt.Errorf("predeploy check failed: %w", err)
}

if err := deploy(ctx, out, artifacts); err != nil {
    if strings.Contains(err.Error(), "unable to connect to Kubernetes") {
        log.Errorf("check VPN/cluster status and kubeconfig context: %v", err)
    }
    return err
}

When it happens

Trigger: FailIfClusterIsNotReachable(k.kubectl.KubeContext) returns an error during Deploy — API server endpoint unreachable, kubeconfig context invalid, VPN off, or expired credentials making a probe request fail.

Common situations: Working remotely without VPN; minikube/kind cluster stopped; context switched to a deleted GKE/EKS cluster; KUBECONFIG env var pointing to wrong file; clock skew invalidating tokens.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• unable to connect to Kubernetes: %w
• unable to connect to Kubernetes: %w
• getting Kubernetes client: %w
• unable to connect to Kubernetes: %w
• kubectl delete: %w

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