ArgoCD sync stuck in Progressing: how to debug

TL;DR

An ArgoCD sync stuck in Progressing means ArgoCD applied the manifests but the resources never reached a healthy state, or a hook/pre-sync step is hanging. Check the application's resource tree for which resource is not healthy, then look at that resource's events: usually a pod crash loop, a failing job hook, or a sync wave waiting on something that will never complete.

Error / query

ArgoCD sync stuck in Progressing: how to debug

Use this skill when

• argocd app get shows Sync: Progressing for a long time with no movement
• The UI shows the app yellow/blue with resources stuck in Progressing
• A sync operation never completes or times out
• It worked before and now hangs after a manifest change

Not for this skill when

• Sync status is OutOfSync (nothing applied yet; diff and sync instead)
• Sync status is Unknown or Error (ArgoCD cannot reach the cluster or the repo)
• Resources are healthy but the app shows degraded (health assessment config, not sync)
• You are debugging Git webhook delivery to ArgoCD (repo connectivity, not sync progress)

Steps

Step 1: See which resources are not progressing

argocd app get [app-name] --show-resources

Expected: the resource table shows per-resource health and sync state. One or two resources stuck in Progressing while the rest are Healthy/Synced tells you exactly where to look.

Step 2: Check for hanging hooks and sync waves

argocd app get [app-name] -o json | python3 -c "
import json,sys
d=json.load(sys.stdin)
for r in d['status']['resources']:
    if r.get('hook') or 'wave' in str(r.get('info','')):
        print(r['kind'], r['name'], r.get('hook'), r['status'])
"

Expected: hooks (PreSync/Sync/PostSync jobs) that never completed block the whole sync. A PreSync hook pod in CrashLoopBackOff is the classic hang.

Step 3: Inspect the stuck resource in the cluster

kubectl get [kind] [name] -n [namespace] -o yaml | grep -A 10 "conditions:\|status:"
kubectl describe [kind] [name] -n [namespace] | tail -30

Expected: the resource's own status explains the wait: a Deployment with unavailable replicas, a Job that never completes, a pod crash looping. Fix the underlying resource; ArgoCD is just reporting it.

Step 4: Look at ArgoCD's sync operation details

argocd app history [app-name] | head -5
argocd app get [app-name] -o json | python3 -c "
import json,sys
op=json.load(sys.stdin)['status'].get('operationState',{})
print(op.get('phase'), op.get('message'))
"

Expected: the operation phase and message, e.g. Running with a sync-wave wait message. If the message names a specific resource or hook, go back to step 3 for that resource.

Step 5: Terminate the stuck operation if the underlying issue is fixed

argocd app terminate-op [app-name]
argocd app sync [app-name]

Expected: the hung operation clears and a fresh sync runs to completion. Only terminate after fixing the stuck resource; terminating without a fix just re-hangs on the next sync.

Variant phrasings

"argocd sync never finishes"

Same thing. Steps 1-2 find the hanging resource or hook in most cases.

"argocd application stuck syncing"

Check the operation state (step 4) for whether it is waiting on a resource, a hook, or ArgoCD itself.

"argocd pre-sync hook hanging"

The hook job/pod is failing or never completes. Fix or delete the hook resource; consider hook-delete-policy so finished hooks clean up.

Why it happens

ArgoCD's Progressing means "I applied everything, but the cluster has not converged to healthy yet." ArgoCD waits on Kubernetes status conditions, so a Deployment whose pods crash, a Job that never succeeds, or a hook that hangs all keep the sync in Progressing indefinitely. The sync is stuck because the desired state is not actually achievable, not because ArgoCD is broken.

Edge cases and pitfalls

• Custom resources need a health check (lua script or argocd-cm config); without one ArgoCD may wait forever on a CR that is actually fine.
• Sync waves: a wave-N resource that can never become healthy blocks all higher waves silently; check wave annotations.
• Sync with prune on a resource another controller recreates causes a progress loop; check for fighting controllers.
• ApplicationSets generating duplicate resources confuse the sync state; verify the generated app list.
• Do not keep pressing sync on a hung operation; terminate it first (step 5), otherwise operations queue behind the stuck one.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_iCd027C0IP7Sq08R4mMlJw