Diagnosing Argo CD Applications Stuck in Unknown or Error Sync Status

Problem: Argo CD Application stuck in Unknown or Error

An Argo CD Application is a custom resource that tracks manifests from a source, usually a Git repository. When the Argo CD repo-server cannot reach or authenticate against that repository, the Application stops at OutOfSync, Unknown, or Error. The UI may show ComparisonError or an rpc error, and the controller generates no manifests.

Use this guide when a previously syncing Application breaks, or when a new Application never produces resources. Match the repo-server error to a cause in the table below, then apply only the matching fix.

Symptoms and likely causes

Observable symptom	Likely cause	Where to confirm
Sync status Unknown; repo-server logs show TLS handshake or certificate errors	Self-signed or custom certificate authority is not trusted by repo-server	argocd-repo-server logs; argocd-tls-certs-cm ConfigMap
Sync status Error; logs show host key verification failed	SSH known_hosts does not contain the Git server's public key	argocd-repo-server logs; argocd-ssh-known-hosts-cm ConfigMap
ComparisonError or 401/403 responses; repository URL is reachable	Missing, mislabeled, or incorrect repository credential secret	argocd-repo-server logs; Secret in the argocd namespace
Application stays Unknown with no repository activity	Proxy, firewall, network policy, or malformed repository URL blocks reachability	Connectivity test from a pod in the argocd namespace
Some repositories sync; one specific repository does not	The AppProject does not list the repository in sourceRepos	AppProject spec.sourceRepos

Ordered checks

1. Check 1: Read the Application status and conditions

   Where to run: workstation with kubectl context pointed at the Argo CD cluster. Required permissions: read applications.argoproj.io.

   kubectl get application  -n argocd -o yaml

   Expected check: STATUS is OutOfSync, Unknown, or Error; the status.conditions list includes a reason and message such as a connection or authentication failure. Risk: none; read-only.

2. Check 2: Inspect repo-server logs

   Where to run: same cluster context. Required permissions: read pods and logs.

   kubectl logs -n argocd deploy/argocd-repo-server --tail=100

   Expected check: repeated lines mentioning TLS, x509, host key, authentication, rpc error, or ComparisonError. Risk: none; read-only.

3. Check 3: Verify the repository credential Secret

   Where to run: same cluster context. Required permissions: read Secrets.

   kubectl get secret  -n argocd -o yaml

   Expected check: the Secret carries the label argocd.argoproj.io/secret-type: repository and contains data keys matching the auth method, such as username and password for HTTPS or sshPrivateKey for SSH. Risk: printing a Secret may expose credentials in your terminal history.

4. Check 4: Test repository connectivity from inside the cluster

   Where to run: a debug pod in the argocd namespace so it shares the repo-server's network policies. Required permissions: create and run pods.

   kubectl run git-check --rm -i --restart=Never --image=alpine/git -n argocd -- \
     git ls-remote https://github.com/example/ops-config.git

   Replace https://github.com/example/ops-config.git with the Application's spec.source.repoURL. Expected check: the command lists remote refs. A failure reproduces the connection error outside Argo CD. Risk: credentials typed on the command line can appear in the process list; mount a Secret or use interactive input instead when testing with passwords.

5. Check 5: Confirm project scoping allows the repository

   Where to run: same cluster context. Required permissions: read AppProjects.

   kubectl get appproject  -n argocd -o yaml

   Expected check: spec.sourceRepos contains the repository URL or a matching wildcard such as https://github.com/*. Risk: none; read-only.

Fixes tied to findings

Fix 1: Recreate or correct the repository credential Secret

Apply when Check 2 or Check 3 shows an authentication failure. Create the Secret in the argocd namespace:

kubectl create secret generic repo-credentials -n argocd \
  --from-literal=username=git \
  --from-literal=password='REPLACE_WITH_TOKEN_OR_PASSWORD'
kubectl label secret repo-credentials -n argocd argocd.argoproj.io/secret-type=repository

For SSH, use --from-file=sshPrivateKey= instead of username and password. Confirm the exact data keys and any required annotations for your Argo CD minor version before applying; formats vary between releases. The repo-server generally picks up Secret changes without a restart. Verify with Check 2 after the change.

Fix 2: Add the Git host to known_hosts

Apply when Check 2 shows a host key verification failure for an SSH repository. Retrieve the host's public key, for example with ssh-keyscan from a trusted machine, then add it to the argocd-ssh-known-hosts-cm ConfigMap in the argocd namespace. After editing, rollout restart the repo-server:

kubectl rollout restart deploy/argocd-repo-server -n argocd

Risk: the restart causes a brief period during which the repo-server cannot generate manifests.

Fix 3: Trust a self-signed or custom certificate authority

Apply when Check 2 shows x509 or TLS handshake errors for an HTTPS repository using a private CA. Add the CA certificate to the argocd-tls-certs-cm ConfigMap in the argocd namespace, then rollout restart the repo-server. Confirm the ConfigMap key names and certificate format for your deployed Argo CD version before editing.

Fix 4: Correct the repository URL or project scope

Apply when Check 4 fails because of a malformed URL, or when Check 5 shows the repository is missing from the AppProject. Fix spec.source.repoURL on the Application, or add the URL or a wildcard to spec.sourceRepos on the AppProject. Apply changes through Git or the Argo CD CLI rather than editing the Application directly with kubectl, to avoid drift.

Rollback for state-changing fixes

Fixes 1 through 3 change cluster state. Before editing a Secret or ConfigMap, back it up:

kubectl get secret repo-credentials -n argocd -o yaml > repo-credentials-backup.yaml
kubectl get configmap argocd-ssh-known-hosts-cm -n argocd -o yaml > known-hosts-backup.yaml

To roll back, reapply the backup file and rollout restart the repo-server again so it reloads the previous configuration.

Escalation criteria

Escalate to the platform or Argo CD administrator when any of the following is true:

• argocd-repo-server pods are in CrashLoopBackOff after credential and network fixes.
• Redis or the Kubernetes API/etcd layer backing Argo CD is unhealthy.
• Required Argo CD custom resource definitions are missing.
• Failures persist after correcting credentials, known_hosts, TLS, URL, and project scope.
• The fix requires corporate proxy, firewall, or certificate-authority changes; involve platform security for those.
• Logs indicate a controller defect rather than a configuration error; engage the Argo CD maintainers with version and log details.

Verify the result

After applying a fix, confirm recovery with these read-only checks:

• kubectl get applications -n argocd -o wide shows STATUS Synced and HEALTH Healthy.
• argocd app get shows a successful operation state and no error conditions.
• kubectl logs -n argocd deploy/argocd-repo-server --tail=50 no longer repeats the authentication or TLS error.
• The connectivity test from Check 4 completes and lists remote refs.

Limitations

• Log messages, secret formats, and feature flags change across Argo CD minor versions. Verify syntax against the deployed version before applying changes.
• Do not store plaintext credentials in Git. Use Argo CD repository Secrets or an external secret manager, and restrict access with RBAC.
• Changing TLS, SSH known_hosts, or proxy settings requires a rolling restart of argocd-repo-server; plan for brief unavailability of manifest generation.
• Avoid manual kubectl edits to Application custom resources unless necessary; prefer Git commits or the Argo CD CLI to prevent drift.