unable to create Kubernetes client for remote cluster %q: %w

Error message

unable to create Kubernetes client for remote cluster %q: %w

What it means

initClients fails when creating the Kubernetes client for the remote (multi-cluster) target cluster via k8s.NewClient. The remote cluster name is used to find/construct client configuration; any failure there aborts multi-cluster setup since c.dst is required.

Source

Thrown at cilium-cli/connectivity/check/context.go:971

// initClients assigns the k8s clients used for connectivity tests.
// in the event that this is a multi-cluster test scenario the destination k8s
// client is set to the cluster provided in the MultiCluster parameter.
func (ct *ConnectivityTest) initClients(ctx context.Context) error {
	c := &deploymentClients{
		src: ct.client,
		dst: ct.client,
	}

	if ctx.Err() != nil {
		return ctx.Err()
	}

	if ct.params.MultiCluster != "" {
		multiClusterClientLock.Lock()
		defer multiClusterClientLock.Unlock()
		dst, err := k8s.NewClient(ct.params.MultiCluster, "", ct.params.CiliumNamespace, ct.params.ImpersonateAs, ct.params.ImpersonateGroups)
		if err != nil {
			return fmt.Errorf("unable to create Kubernetes client for remote cluster %q: %w", ct.params.MultiCluster, err)
		}

		c.dst = dst
	}

	ct.clients = c

	return nil
}

// errNoCiliumPods is returned by initCiliumPods when a cluster runs no Cilium
// agent, so that callers which tolerate this can tell it apart from a failure
// to reach the Kubernetes API.
var errNoCiliumPods = errors.New("no cilium agent pods found")

// initCiliumPods fetches the Cilium agent pod information from all clients
func (ct *ConnectivityTest) initCiliumPods(ctx context.Context) error {
	for _, client := range ct.clients.clients() {

View on GitHub (pinned to ac7b90affa)

Solutions

Confirm a kubeconfig context exists for the cluster name passed to --multi-cluster (kubectl config get-contexts) and pass a valid --context if needed
Run cilium-cli clustermesh connect/status to verify inter-cluster connectivity and config
Check --impersonate-as/--impersonate-groups values are valid
Re-authenticate (kubectl login / refresh token) if credentials expired

Example fix

// before
cilium-cli connectivity test --multi-cluster prd-west
# no such context: prd-west
// after
cilium-cli connectivity test --multi-cluster prod-west --context prod-west

Defensive patterns

Strategy: validation

Validate before calling

ctxs, _ := run("kubectl config get-contexts -o name")
if !slices.Contains(ctxs, multiClusterName) {
	return fmt.Errorf("context %q for --multi-cluster not found in kubeconfig", multiClusterName)
}

Try / catch

if err := ct.Run(ctx); err != nil && strings.Contains(err.Error(), "remote cluster") {
	// fix kubeconfig / clustermesh, then retry
}

Prevention

Merge peer-cluster credentials into the kubeconfig before running
Name --multi-cluster exactly as the kubeconfig context/cluster
Validate clustermesh status before connectivity tests
Keep impersonation flags consistent across clusters

When it happens

Trigger: --multi-cluster <name> is set and k8s.NewContext/NewClient cannot build a client for that cluster: no matching kubeconfig context, missing/clusted-config file, bad impersonation args, or unreachable API server.

Common situations: Typo in --multi-cluster name (must match context/cluster name); missing kubeconfig entries for the peer cluster; running inside a cluster without the cilium-clustermesh config; expired tokens.

Related errors

AI-assisted analysis of cilium/cilium@ac7b90affa (2026-08-31). Data as JSON: /api/errors/2660b8e9ff26dfd4. Report an issue: GitHub.