Debug Why ArgoCD Shows Out of Sync (2026)

Argo CD showing an "OutOfSync" status means the desired state defined in your Git repository doesn’t match the actual state of your application running in your Kubernetes cluster.

Let’s dive into why this happens and how to fix it.

Common Causes for OutOfSync Status

Manual Cluster Changes: Someone directly modified resources in the Kubernetes cluster using kubectl apply or the Kubernetes dashboard, bypassing Argo CD.
- Diagnosis:
```
kubectl get <resource_type> <resource_name> -n <namespace> -o yaml > cluster_state.yaml
git diff --no-index cluster_state.yaml <path/to/your/repo/resource.yaml>
```
  Look for differences between the cluster_state.yaml (what’s actually in the cluster) and your Git repository file.
- Fix:
  - Option A (Preferred): Update your Git repository to match the cluster state. Then, Argo CD will sync automatically or you can trigger a sync manually.
  - Option B (If cluster changes were accidental): Revert the changes in the cluster using kubectl apply -f <path/to/your/repo/resource.yaml> to force it back to the desired state.
- Why it works: Argo CD’s core principle is GitOps. It expects Git to be the single source of truth. If the cluster deviates, it flags it. Reconciling the two states brings them back into alignment.
Argo CD Application Configuration Drift: The Application resource itself in Kubernetes has been modified. This could be changes to the spec.source (e.g., changing the Git branch, path, or revision) or spec.destination (e.g., changing the target cluster or namespace).
- Diagnosis:
```
kubectl get application <application_name> -n <argocd_namespace> -o yaml > cluster_app.yaml
git diff --no-index cluster_app.yaml <path/to/your/repo/application.yaml>
```
  Compare the application.yaml in your Argo CD application’s configuration with the one Argo CD sees in the cluster.
- Fix:
  - Option A (Preferred): If the changes to the Application resource are intentional and correct, ensure they are committed to the Git repository that Argo CD monitors for its own configuration.
  - Option B (If cluster changes were accidental): Revert the Application resource in the cluster: kubectl apply -f <path/to/your/repo/application.yaml>.
- Why it works: The Argo CD Application CRD is itself a Kubernetes resource. If its definition in the cluster doesn’t match what Argo CD believes it should be (based on its own source), it becomes out of sync.
Resource Health Status Mismatch: A resource in the cluster is not in a Healthy state according to Argo CD’s health checks, even if its manifest matches Git. Argo CD considers the application out of sync if any of its managed resources are unhealthy.
- Diagnosis:
```
argocd app get <application_name>
```
  Look for the health status of individual resources listed under the application. It will often show Degraded, Missing, or Unknown.
- Fix: Investigate the unhealthy resource. For example, if a Pod is CrashLoopBackOff:
```
kubectl logs <pod_name> -n <namespace>
kubectl describe pod <pod_name> -n <namespace>
```
  Address the root cause of the resource’s unhealthy state (e.g., image pull errors, configuration issues, resource limits). Once the resource becomes Healthy, Argo CD will often resolve the OutOfSync status automatically.
- Why it works: Argo CD aims to deploy healthy applications. If a component is failing, the application as a whole is not in its desired healthy state, hence the OutOfSync flag.
Resource Customization Issues (Kustomize/Helm): If you’re using Kustomize or Helm for templating, there might be a mismatch between the rendered manifest in Git and what Argo CD is trying to apply, or the rendering process itself failed. This can happen if kustomization.yaml or Chart.yaml references are incorrect, or if the build process (e.g., kustomize build) produces different output than expected.
- Diagnosis:
  - Kustomize: Manually build the Kustomize output and compare it with what Argo CD is reporting.
```
kustomize build <path/to/your/kustomization/dir> > rendered_local.yaml
kubectl get <resource_type> <resource_name> -n <namespace> -o yaml > cluster_state.yaml
diff rendered_local.yaml cluster_state.yaml
```
  - Helm: Use helm template to inspect the rendered charts.
```
helm template <release_name> <chart_path> --namespace <namespace> --values <values_file.yaml> > rendered_helm.yaml
kubectl get <resource_type> <resource_name> -n <namespace> -o yaml > cluster_state.yaml
diff rendered_helm.yaml cluster_state.yaml
```
- Fix: Correct the Kustomize overlays or Helm values/chart definitions in your Git repository to ensure the rendered output matches your intended state. Re-sync the Argo CD application.
- Why it works: Argo CD relies on the templating tool to generate the final Kubernetes manifests. If the generated manifests don’t match the cluster state (or are malformed due to incorrect templating), the sync will fail.
Resource Deletion Not Reflected: A resource was deleted directly from the cluster (kubectl delete), but Argo CD hasn’t yet reconciled this change because it’s still present in the Git repository. Argo CD sees the resource in Git but not in the cluster, marking it as OutOfSync.
- Diagnosis:
```
kubectl get <resource_type> <resource_name> -n <namespace>
```
  If this command returns "not found," but the resource is in your Git repo, this is the cause.
- Fix: Remove the resource definition from your Git repository. Argo CD will then detect the removal and prune the resource from the cluster on the next sync.
- Why it works: Argo CD’s desired state is defined by Git. If a resource is removed from Git, Argo CD’s desired state is for that resource not to exist, and it will act to enforce that.
Argo CD Controller Issues: The Argo CD controller itself might be experiencing problems, such as being overloaded, stuck, or having communication issues with the Kubernetes API server.
- Diagnosis:
```
kubectl get pods -n argocd
kubectl logs <argocd_controller_pod_name> -n argocd
kubectl describe pod <argocd_controller_pod_name> -n argocd
```
  Check for restarts, error messages in logs, or resource constraints on the controller pods.
- Fix: Restart the Argo CD controller pods:
```
kubectl rollout restart deployment argocd-server -n argocd
kubectl rollout restart deployment argocd-application-controller -n argocd
```
  If resource constraints are an issue, adjust the resource requests/limits for the Argo CD deployment.
- Why it works: The controller is the engine that compares Git state to cluster state and applies changes. If it’s not functioning correctly, it cannot accurately report or enforce the desired state.
Resource Version Mismatch (Less Common, but possible): In rare cases, especially with complex CRDs or controllers, the resourceVersion field in the cluster might get out of sync with what Argo CD expects, leading to reconciliation loops or OutOfSync flags. This is often a symptom of a deeper issue.
- Diagnosis: Examine the Argo CD application controller logs for resourceVersion related errors or Conflict errors during sync operations.
- Fix: Often, a clean sync or a restart of the Argo CD controller can resolve transient resourceVersion issues. For persistent problems, it might indicate an issue with the specific controller managing that CRD.
- Why it works: Kubernetes uses resourceVersion for optimistic concurrency control. If Argo CD or the API server misinterprets or mismanages this, it can cause update conflicts.

After resolving the OutOfSync status, the next common issue you might encounter is the application entering a Degraded state if the underlying resources fail to become healthy.