How to fix ArgoCD cluster connection failed in Kubernetes

KubernetesINTERMEDIATEHIGHUpdated Dec 6, 2025· 133 views

ArgoCD fails to connect to a managed cluster due to incorrect credentials, network blocking, or invalid kubeconfig. The cluster status shows "Unknown" or connection attempts timeout. Fix by verifying the cluster URL, updating kubeconfig credentials, checking firewall rules between ArgoCD and the cluster, and ensuring RBAC permissions.

Quick fix

Fixes ArgoCD cluster connection failed

# Inside ArgoCD server pod
kubectl exec -it <argocd-server-pod> -n argocd -- /bin/sh

# Test DNS resolution and connectivity to cluster API
curl -k https://<cluster-api-url>:6443
ncstat -zv <cluster-api-host> 6443
  1. Verify cluster URL and connectivity
  2. List and inspect cluster configuration
  3. Export and validate kubeconfig credentials
  4. Check argocd-manager ServiceAccount permissions
kubernetes — error
# Inside ArgoCD server pod
kubectl exec -it <argocd-server-pod> -n argocd -- /bin/sh
# Test DNS resolution and connectivity to cluster API
curl -k https://<cluster-api-url>:6443
ncstat -zv <cluster-api-host> 6443
ArgoCD cluster connection failed

What this error means

When ArgoCD cannot establish a connection to a managed cluster, it indicates a problem with the cluster credentials stored in the argocd-manager Secret, network connectivity between the ArgoCD server and the target cluster API, or RBAC permissions preventing access. ArgoCD stores cluster configuration as a Kubernetes Secret in the argocd namespace containing the bearer token, CA certificate, and cluster URL. If any of these are invalid or if the network path is blocked, the cluster appears as "Unknown" and deployments fail.

Typical symptoms

  • Cluster status shows "Unknown" or "Failed" in ArgoCD UI
  • CLI shows "cluster connection failed" error
  • Unable to sync applications deployed to that cluster
  • API server returns "connection refused" or "timeout" errors
  • argocd-application-controller logs show connection errors
  • Cluster health check shows 0/5 healthy components
  • Manual kubectl commands work but ArgoCD cannot connect

Common causes

  1. Incorrect cluster URL or API server endpoint in cluster configuration
  2. Bearer token in kubeconfig expired or revoked
  3. Network firewall or security group blocking traffic between ArgoCD and cluster
  4. Cluster certificate (CA) mismatch or self-signed cert validation failure
  5. RBAC ServiceAccount (argocd-manager) lacks permissions on target cluster
  6. Kubeconfig contains embedded certificate data that ArgoCD cannot parse
  7. TLS verification enabled but certificate chain incomplete
  8. Network policy on cluster preventing inbound from ArgoCD pod IP

How to fix "ArgoCD cluster connection failed"

1Verify cluster URL and connectivity

Check that the cluster URL is correct and reachable from the ArgoCD server pod:

bash
# Inside ArgoCD server pod
kubectl exec -it <argocd-server-pod> -n argocd -- /bin/sh

# Test DNS resolution and connectivity to cluster API
curl -k https://<cluster-api-url>:6443
ncstat -zv <cluster-api-host> 6443

If curl returns a certificate error but connects, this confirms basic network access. The error is likely certificate validation, not connectivity.

2List and inspect cluster configuration

View the current cluster configuration:

bash
argocd cluster list
argocd cluster get <cluster-name>

Look for:
- Correct API server URL
- Server address format (should be https://...)
- Cluster name matching your intention

Use CLI to inspect the Secret directly:

bash
kubectl get secret <cluster-secret-name> -n argocd -o yaml
3Export and validate kubeconfig credentials

Use the ArgoCD admin tool to export kubeconfig and test it:

bash
# Extract kubeconfig from the cluster Secret
argocd admin cluster kubeconfig <cluster-name> > cluster.kubeconfig

# Test connection with extracted kubeconfig
kubectl --kubeconfig=cluster.kubeconfig cluster-info
kubectl --kubeconfig=cluster.kubeconfig auth can-i get pods --all-namespaces

If the exported kubeconfig works locally but ArgoCD still fails, the issue is in how ArgoCD is configured to use it.

4Check argocd-manager ServiceAccount permissions

Verify the argocd-manager account has cluster-admin or necessary RBAC on the target cluster:

bash
# On the TARGET cluster (not ArgoCD cluster)
kubectl get serviceaccount argocd-manager -n argocd
kubectl get clusterrolebinding -o jsonpath='{range .items[*]}{.metadata.name}{"\n"}{end}' | grep argocd
kubectl describe clusterrolebinding argocd-manager-role

If argocd-manager is missing or has insufficient permissions, re-add the cluster with correct permissions:

bash
argocd cluster add <cluster-context> --name <cluster-name>
5Re-add the cluster with proper authentication

Remove and re-add the cluster to reset credentials:

bash
# From ArgoCD cluster
argocd cluster rm <cluster-name>
argocd cluster add <cluster-context>

Make sure:
- You are logged into the target cluster context (check with: kubectl config current-context)
- The ServiceAccount argocd-manager is created on the target cluster
- Your user has admin permissions on the target cluster

For external clusters with certificate issues, use explicit flags:

bash
argocd cluster add <context> --name <cluster-name> --skip-confirmation
6Check network policies and firewall rules

Ensure network connectivity between ArgoCD pod and cluster API:

bash
# From ArgoCD server pod, test connectivity
kubectl exec -it <argocd-server-pod> -n argocd -- bash
nc -zv <api-server-host> 6443

# Check if there's a Network Policy blocking egress
kubectl get networkpolicies -n argocd
kubectl describe networkpolicy <policy-name> -n argocd

For cloud providers (AWS/GKE/AKS), check security groups:
- AWS: Security group of ArgoCD node must allow outbound on port 6443
- GKE: Firewall rule must allow traffic from ArgoCD node to target cluster API
- AKE: Network Security Group must permit argocd-server outbound traffic

7Review ArgoCD server logs for detailed errors

Get detailed error messages from ArgoCD components:

bash
# Check application-controller logs
kubectl logs -f deployment/argocd-application-controller -n argocd | grep -i "connection\|error\|cluster"

# Check server logs
kubectl logs -f deployment/argocd-server -n argocd | grep -i "cluster"

# Check repo-server (handles git access)
kubectl logs -f deployment/argocd-repo-server -n argocd

Look for:
- "x509: certificate signed by unknown authority" (TLS issue)
- "connection refused" (network issue)
- "Unauthorized" (RBAC issue)
- "invalid token" (credential issue)

Advanced notes

Certificate validation issues are common when using self-signed or internal CA certificates. You can disable TLS verification as a temporary diagnostic step with --insecure flag, but for production always fix the certificate chain. For multi-cluster setups, use declarative cluster management (ApplicationSet) instead of CLI. Some organizations use Rancher or other cluster managers that provide additional abstraction—ensure ArgoCD can reach the actual Kubernetes API endpoint, not just the management interface. If "argocd-manager" ServiceAccount is missing on the target cluster, it means the argocd cluster add command did not complete successfully; re-run it or manually create the account. Network policies inside Kubernetes can also block communication; consider using service mesh or explicit egress rules if needed.

Frequently asked questions

What does "ArgoCD cluster connection failed" mean?
When ArgoCD cannot establish a connection to a managed cluster, it indicates a problem with the cluster credentials stored in the argocd-manager Secret, network connectivity between the ArgoCD server and the target cluster API, or RBAC permissions preventing access. ArgoCD stores cluster configuration as a Kubernetes Secret in the argocd namespace containing the bearer token, CA certificate, and cluster URL. If any of these are invalid or if the network path is blocked, the cluster appears as "Unknown" and deployments fail.
How do I fix "ArgoCD cluster connection failed"?
ArgoCD fails to connect to a managed cluster due to incorrect credentials, network blocking, or invalid kubeconfig. The cluster status shows "Unknown" or connection attempts timeout. Fix by verifying the cluster URL, updating kubeconfig credentials, checking firewall rules between ArgoCD and the cluster, and ensuring RBAC permissions.
What causes "ArgoCD cluster connection failed"?
Incorrect cluster URL or API server endpoint in cluster configuration Bearer token in kubeconfig expired or revoked Network firewall or security group blocking traffic between ArgoCD and cluster
Is the "ArgoCD cluster connection failed" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading