ArgoCD Troubleshooting | DevOps QuickRef

OutOfSync

The live cluster state doesn't match Git. This is a normal, expected status — not an error — until you decide whether to sync.

argocd app diff my-app

Shows exactly what's different, resource by resource, before deciding to sync.

Persistent OutOfSync after syncing

If an app goes back to OutOfSync immediately after a successful sync, something outside ArgoCD is mutating the resource — a mutating admission webhook, an HPA changing replica count, or a controller (like AWS Load Balancer Controller) writing status fields back onto the object. Configure ignoreDifferences for fields ArgoCD shouldn't fight over.

Degraded

The application synced, but a resource's live health check is failing — a Deployment with pods not becoming Ready, a Job that failed, a Service with no endpoints.

argocd app get my-app

Shows per-resource health status — identifies exactly which resource is Degraded, not just that the app as a whole is.

kubectl describe pod POD_NAME -n NAMESPACE

Once you know which resource is unhealthy, standard Kubernetes troubleshooting applies — see the Kubernetes Troubleshooting page for CrashLoopBackOff, probe failures, and more.

SyncFailed

The sync operation itself errored out — this is different from OutOfSync (a diff exists) or Degraded (synced but unhealthy); SyncFailed means applying the manifests failed.

argocd app get my-app --show-operation

Shows the specific error from the failed sync operation.

Common SyncFailed causes

A resource that already exists and isn't owned by ArgoCD (missing the tracking label/annotation), a validation webhook rejecting the manifest, insufficient RBAC for the ArgoCD service account in the destination namespace, or a resource ordering problem (a CRD applied in the same sync wave as a custom resource that depends on it).

Repository Authentication Error

ArgoCD can't clone or read the Git repository a source application points at.

argocd repo list

Lists configured repositories and their connection status.

argocd repo get https://github.com/org/repo.git

Shows the specific auth error for one repository.

Common causes

An expired or rotated deploy key/token, a repo URL using SSH when the credential is HTTPS-based (or vice versa), or the credential simply never configured for that specific repo (ArgoCD credentials are matched by URL prefix).

Manifest Generation Error

ArgoCD successfully reads the repo, but fails to render manifests from it — most often a Helm or Kustomize error.

argocd app manifests my-app

Attempts to render manifests directly, surfacing the templating error ArgoCD hit.

Common causes

A Helm chart referencing a values file that doesn't exist at the configured path, a Kustomize overlay referencing a base that moved, or a missing required Helm value with no default — reproduce locally with helm template or kustomize build against the same path to get a faster feedback loop than round-tripping through ArgoCD.