How to fix ArgoCD out of sync in Kubernetes

KubernetesINTERMEDIATEHIGHUpdated Dec 6, 2025· 136 views

ArgoCD shows resources as out of sync when the cluster state drifts from the Git repository. This occurs due to auto-generated values, mutating webhooks, or resource normalization. Use ignoreDifferences, sync options, or enable auto-healing to resolve drift issues.

Quick fix

Fixes ArgoCD out of sync

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
spec:
  ignoreDifferences:
  - group: apps
    kind: Deployment
    jsonPointers:
    - /spec/template/spec/containers/0/image
  1. Check the ArgoCD UI diff view
  2. Review application logs and controller output
  3. Add ignoreDifferences for known drift
  4. Disable auto-generation in Helm charts
kubernetes — error
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
spec:
  ignoreDifferences:
  - group: apps
    kind: Deployment
    jsonPointers:
    - /spec/template/spec/containers/0/image
ArgoCD out of sync

What this error means

In ArgoCD, the "out of sync" status indicates that the Kubernetes cluster state no longer matches the desired state defined in your Git repository. This drift can happen when a controller or webhook modifies resources after they are applied, when Kubernetes normalizes resource values, or when Helm charts generate unique values on each template invocation. ArgoCD continuously detects these differences and reports the application as out of sync, preventing automated deployment workflows from proceeding.

Typical symptoms

  • Application shows "OutOfSync" status in ArgoCD UI
  • Running sync operation does not resolve the out of sync status
  • Diff view shows differences even though resources were recently synced
  • Auto-sync is disabled or not resolving the drift
  • Manual syncs succeed but resources drift again immediately
  • Helm chart values change on every template rendering
  • Mutating webhooks alter resources after deployment
  • Kubernetes normalizes resource fields differently than the manifest

Common causes

  1. Helm chart using auto-generation functions like randAlphaNum or now that produce different values on each template render
  2. Mutating webhooks or admission controllers modifying resources after submission to Kubernetes
  3. Kubernetes resource normalization converting values to different formats than the source manifests
  4. Generated secrets or certificates being updated by controllers automatically
  5. Image pull policies or other fields being defaulted differently by Kubernetes
  6. Custom resource definitions being enhanced by webhooks post-deployment
  7. Service mesh sidecars being injected and modifying resource specs
  8. Resource limits being normalized or converted to different units

How to fix "ArgoCD out of sync"

1Check the ArgoCD UI diff view

Open the ArgoCD UI, select your application, and view the Diff tab to see which fields are causing the out of sync status. This helps identify the exact differences between Git and cluster state.

2Review application logs and controller output

Check the ArgoCD application controller logs for detailed information about what resources are drifting. Use: kubectl logs -n argocd -l app.kubernetes.io/name=argocd-application-controller | grep <app-name>

3Add ignoreDifferences for known drift

If the drift is expected and harmless, configure ignoreDifferences in your Application manifest:

yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
spec:
  ignoreDifferences:
  - group: apps
    kind: Deployment
    jsonPointers:
    - /spec/template/spec/containers/0/image
4Disable auto-generation in Helm charts

If using Helm, remove or conditionally disable functions that auto-generate values. Replace functions like {{ randAlphaNum 10 }} with fixed values or externalized parameters that are controlled via values.yaml.

5Use sync options to handle drift

Add sync options to your Application to use Replace strategy instead of Apply:

yaml
spec:
  syncPolicy:
    syncOptions:
    - RespectIgnoreDifferences=true
    - Replace=true
6Enable auto-healing and auto-sync

Configure automatic synchronization to continuously fix drift:

yaml
spec:
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
7Apply diffing customizations globally

Configure resource customizations in the argocd-cm ConfigMap to ignore specific fields globally:

yaml
resource.customizations.ignoreDifferences.all: |
  jsonPointers:
  - /spec/template/spec/containers/0/image
8Manually force sync if needed

As a last resort, force sync to reset the application:

bash
argocd app sync <app-name> --force

Advanced notes

For production environments, prefer ignoreDifferences over force sync as it acknowledges expected drift rather than blindly resetting state. If using service mesh (Istio, Linkerd), sidecar injection often causes false positives in diff detection - configure ignoreDifferences for injected fields. Consider using Kustomize or Helm with explicit value overrides rather than auto-generation functions for predictable deployments. Monitor sync frequency as continuous drift indicates deeper configuration issues.

Frequently asked questions

What does "ArgoCD out of sync" mean?
In ArgoCD, the "out of sync" status indicates that the Kubernetes cluster state no longer matches the desired state defined in your Git repository. This drift can happen when a controller or webhook modifies resources after they are applied, when Kubernetes normalizes resource values, or when Helm charts generate unique values on each template invocation. ArgoCD continuously detects these differences and reports the application as out of sync, preventing automated deployment workflows from proceeding.
How do I fix "ArgoCD out of sync"?
ArgoCD shows resources as out of sync when the cluster state drifts from the Git repository. This occurs due to auto-generated values, mutating webhooks, or resource normalization. Use ignoreDifferences, sync options, or enable auto-healing to resolve drift issues.
What causes "ArgoCD out of sync"?
Helm chart using auto-generation functions like randAlphaNum or now that produce different values on each template render Mutating webhooks or admission controllers modifying resources after submission to Kubernetes Kubernetes resource normalization converting values to different formats than the source manifests
Is the "ArgoCD out of sync" 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