Disclosure: Some links in this article are affiliate links. We may earn a small commission at no extra cost to you.

ArgoCD Troubleshooting Guide 2026: Fix the 10 Most Common Issues

ArgoCD is reliable, but when things go wrong, the error messages aren’t always helpful. This guide covers the most common ArgoCD issues and how to fix them — from sync failures to performance problems.

1. Application Stuck in “OutOfSync”

Symptoms: ArgoCD shows OutOfSync but the resources look correct in the cluster.

Common causes and fixes:

# Check what ArgoCD thinks is different
argocd app diff my-app

# Force a refresh
argocd app get my-app --refresh

# Hard refresh (re-read from Git)
argocd app get my-app --hard-refresh

Usual suspects:
– Kubernetes adds default fields (like strategy.rollingUpdate) that don’t match your manifests
– Resource tracking mismatch — check argocd.argoproj.io/tracking-id annotations
– Helm generating different output than expected

Fix: Add ignored differences:

spec:
  ignoreDifferences:
    - group: apps
      kind: Deployment
      jsonPointers:
        - /spec/replicas

2. Sync Failed: “ComparisonError”

ComparisonError: failed to load initial state of resource Deployment: deployments.apps is forbidden

Fix: ArgoCD’s service account needs RBAC permissions:

# Check ArgoCD's cluster permissions
kubectl auth can-i list deployments --as=system:serviceaccount:argocd:argocd-application-controller -n default

3. Repository Connection Refused

rpc error: Unable to connect to repository

Fixes:

# Verify repo credentials
argocd repo list

# Remove and re-add
argocd repo rm https://github.com/yourorg/repo.git
argocd repo add https://github.com/yourorg/repo.git --username <user> --password <token>

# For SSH, check the known_hosts
argocd cert list --cert-type ssh

4. Sync Timeout on Large Applications

Symptoms: Sync starts but times out before completion.

# Increase the timeout (default 180s)
argocd app sync my-app --timeout 600

# Or set it in the Application spec
spec:
  syncPolicy:
    syncOptions:
      - ServerSideApply=true  # Faster for large resources

5. Health Status “Degraded” or “Progressing”

ArgoCD checks resource health. Common issues:

Resource	Issue	Fix
Deployment	Pods not ready	Check pod logs, resource limits
Service	No endpoints	Labels don’t match pods
Ingress	No address assigned	Check ingress controller
PVC	Pending	StorageClass not available

# Check why a resource is unhealthy
argocd app resources my-app --output json | jq '.[] | select(.health.status != "Healthy")'

6. “Already Exists” Error During Sync

resource already exists and is not managed by ArgoCD

Fix: Either adopt the existing resource or delete it first:

# Adopt: add the tracking label
kubectl label deployment my-deployment app.kubernetes.io/instance=my-app

# Or delete and let ArgoCD recreate
kubectl delete deployment my-deployment
argocd app sync my-app

7. ArgoCD Server High Memory Usage

ArgoCD caches Git repositories and cluster state. Large repos cause memory pressure.

Fixes:

# Increase memory limits
apiVersion: apps/v1
kind: Deployment
metadata:
  name: argocd-repo-server
spec:
  template:
    spec:
      containers:
        - name: argocd-repo-server
          resources:
            limits:
              memory: 2Gi

Also consider:
– Splitting large repos into smaller ones
– Reducing refresh interval: --app-resync 300 (5 min instead of default 3 min)
– Using shallow clones

8. Webhook Not Triggering Sync

ArgoCD supports webhooks from GitHub, GitLab, and Bitbucket for instant sync:

# Verify webhook is configured
kubectl get configmap argocd-cm -n argocd -o yaml | grep webhook

# Check ArgoCD server logs
kubectl logs -n argocd deployment/argocd-server | grep webhook

9. CRD Installation Order Issues

CRDs must exist before custom resources that use them.

Fix: Use sync waves:

metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "-1"  # CRDs first
---
metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "0"   # Then custom resources

10. SSO/OIDC Login Not Working

# Check the OIDC configuration
kubectl get configmap argocd-cm -n argocd -o yaml

# Verify the redirect URI matches your OIDC provider config
# Common mistake: trailing slash mismatch

Useful Debug Commands

# Application details
argocd app get my-app

# Sync history
argocd app history my-app

# Server logs
kubectl logs -n argocd deployment/argocd-server -f

# Repo server logs (Git/Helm issues)
kubectl logs -n argocd deployment/argocd-repo-server -f

# Controller logs (sync issues)
kubectl logs -n argocd deployment/argocd-application-controller -f

Let's Talk DevOps