Troubleshooting
Most Argo CD problems fall into a handful of patterns. This page starts with a routine that narrows any problem down to a component, then lists common symptoms by area. Each area links to the page that explains the behavior in full.
Start here: find the failing component
Section titled “Start here: find the failing component”Argo CD is a pipeline of components, so the first question is which stage failed.
flowchart LR
A["Repository<br/>reachable?"] --> B["Repo server<br/>renders manifests?"]
B --> C["Controller<br/>compares and syncs?"]
C --> D["Target cluster<br/>accepts the apply?"]
-
Read the Application’s status and conditions. They name the failing stage most of the time.
Terminal window argocd app get catalog-apikubectl get application catalog-api -n argocd -o jsonpath='{.status.conditions}'A
ComparisonErrorpoints at the repository or rendering. A sync failure shows the apply error and the resource that caused it. -
Check the rendered output. If rendering is in doubt, compare what Argo CD generates with what is live.
Terminal window argocd app manifests catalog-api # what Git renders toargocd app manifests catalog-api --source liveargocd app diff catalog-api -
Re-read the source without the cache. A stale cache explains many “it did not update” reports.
Terminal window argocd app get catalog-api --hard-refresh -
Read the component logs. The repo server logs rendering and Git errors, and the application controller logs comparison and sync.
Terminal window kubectl logs -n argocd deploy/argocd-repo-serverkubectl logs -n argocd statefulset/argocd-application-controllerkubectl logs -n argocd deploy/argocd-serverRaise detail temporarily with
controller.log.level,reposerver.log.level, orserver.log.levelset todebuginargocd-cmd-params-cm, then restart the component. Return it toinfoafterwards. -
Check the target cluster. Many sync failures are Kubernetes errors, so
kubectl describeon the failing resource andkubectl get events -n <namespace>often finish the investigation.
Installation and access
Section titled “Installation and access”| Symptom | Likely cause | Fix |
|---|---|---|
metadata.annotations: Too long on install | Client-side apply cannot store the ApplicationSet CRD | Apply with --server-side --force-conflicts. See installation |
| Helm install fails with “already exists” | A manifest-based install is still present | Remove it and the argocd namespace, then reinstall |
Redis HA Pods stay Pending | Fewer than three nodes | Add nodes or use the non-HA topology. See high availability |
| Browser reports too many redirects | The gateway terminated TLS while Argo CD still redirects to HTTPS | Set server.insecure: "true" in argocd-cmd-params-cm |
404 from the gateway for the Argo CD host | No route matches the Host, or the ingress class is wrong | Check the hostname, class or parentRefs, and DNS |
| UI works but the CLI fails | The proxy does not pass gRPC | Log in with --grpc-web. See Web UI and CLI |
x509: certificate signed by unknown authority from the CLI | Self-signed or private-CA certificate on the server | Install a trusted certificate, or use --insecure while testing |
| A ConfigMap change has no effect | The ConfigMap lacks the app.kubernetes.io/part-of: argocd label, or a launch parameter needs a restart | Add the label, then restart the component. See declarative configuration |
| A repository or cluster Secret is ignored | Wrong or missing argocd.argoproj.io/secret-type label, or wrong namespace | Fix the label and apply the Secret in the Argo CD namespace |
Repositories and credentials
Section titled “Repositories and credentials”| Symptom | Likely cause | Fix |
|---|---|---|
authentication required | No credentials, an expired token, or the wrong username | Update the credentials. --upsert overwrites. See TLS and repository credentials |
x509: certificate signed by unknown authority adding a repository | The Git host uses a private CA | argocd cert add-tls <host> with the CA chain |
| SSH host key verification failed | The host key is not in argocd-ssh-known-hosts-cm | ssh-keyscan the host and add it with argocd cert add-ssh |
| SSH key rejected | A passphrase on the key, or the deploy key is on the wrong repository | Use a key without a passphrase, registered on the right repository |
| Redirect with HTTP 301 | The URL lacks the .git suffix the host requires | Use the .git form |
| A new repository ignores the credential template | The URL prefix does not match, or the repository has its own credentials | Check the prefix and remove per-repository credentials |
| Git host rate-limits Argo CD | Polling interval too short for the number of repositories | Lengthen timeout.reconciliation and use webhooks. See CI integration and webhooks |
| A pushed change takes two to three minutes to appear | No webhook, so the poll found it | Configure the webhook |
| Webhook delivery fails with 400 or a signature error | Content type is not application/json, or the secret differs | Fix the content type and compare the secret in argocd-secret |
| Webhook arrives but nothing refreshes | The event’s repository URL differs from the Application’s repoURL | Match the URL form, including .git and HTTPS vs SSH |
Manifest generation
Section titled “Manifest generation”| Symptom | Likely cause | Fix |
|---|---|---|
| A chart or plugin change is not picked up | The cached manifests are still valid | Hard refresh. See CI integration and webhooks |
| A Helm value is ignored | A higher-precedence source overrides it | Check parameters and valuesObject. See rendering tools |
| A Kustomize directory deploys as plain files | No kustomization.yaml at the Application’s path | Point path at the directory that has it |
| Kustomize cannot inflate a Helm chart | --enable-helm is not set | Set kustomize.buildOptions or use a plugin, then restart. See extending Argo CD |
| OCI chart not found | repoURL includes oci://, or no registry credentials | Remove the scheme and add credentials |
Context deadline exceeded | Manifest generation exceeds the timeout | Raise the repo server timeouts, and scale or tune the repo server |
| Repo server restarts with out-of-memory kills | Too many concurrent generations | Lower --parallelismlimit or raise memory |
| Plugin sidecar crash-loops or the plugin is never found | Wrong command, user, plugin.yaml path, or name | Check the three sidecar requirements and the sidecar logs |
| An Application is pruned empty after a plugin failure | A pipe in generate hid the error | Use set -o pipefail |
| Symptom | Likely cause | Fix |
|---|---|---|
A new Application is OutOfSync and nothing deploys | Manual sync is the default | Sync it, or enable automated sync. See sync policies |
| A removed manifest still runs | prune is off | Enable prune, or sync with pruning |
| Auto-sync does not retry after a failure | One attempt per commit and parameter set | Push a new commit, sync manually, or add retry |
| Auto-prune refuses to run | The source renders zero resources | Confirm that is intended, then set allowEmpty: true |
| Sync fails for a custom resource kind | The CRD is created in the same sync | Add SkipDryRunOnMissingResource=true and a retry policy |
| Sync fails because the namespace is missing | The namespace was never created | Add CreateNamespace=true |
metadata.annotations: Too long on a resource | Exceeds the client-side apply limit | Use ServerSideApply=true |
| Sync is rejected for repository or destination | The AppProject does not allow it | Adjust the project. See multi-tenancy and projects |
| Sync stuck on “waiting for completion of hook” | A hook Job never finishes, or the previous run is pending deletion | Inspect the hook. See phases, hooks, and waves |
| Nothing deployed after a failed sync | A PreSync hook failed, which halts the sync | Fix the hook and sync again |
| A hook Job does not run again | The old Job still exists | Set hook-delete-policy: BeforeHookCreation |
| Hooks did not run | The sync was a selective sync | Run a full sync |
| Rollback is rejected | Automated sync is enabled | Disable it, or revert in Git |
| Pipeline sync rejected | The token’s role lacks sync or override, or automated sync is on | Fix the role. See CI integration and webhooks |
| Sync fails after enabling impersonation | No matching destinationServiceAccounts entry, or the service account is missing | Add the entry and create the account. See commit signing and impersonation |
| Application blocked about an unsigned revision | The target commit is not signed by an allowed key | Sign the commit, or fix the policy keys |
| Application stuck deleting | A cascading delete waits on a resource that cannot be removed | Fix that resource. See Applications |
Diffing and health
Section titled “Diffing and health”| Symptom | Likely cause | Fix |
|---|---|---|
OutOfSync right after a successful sync | Something mutates the object after apply | argocd app diff, then add ignoreDifferences. See diffing and ignore rules |
| A field is ignored in the diff but overwritten by sync | The rule applies only to comparison | Add RespectIgnoreDifferences=true |
An operator-created resource keeps the app OutOfSync | It is extraneous in the live state | Annotate the triggering manifest with IgnoreExtraneous |
| A JSON pointer never matches | A key contains / | Write it as ~1 |
Synced but Degraded | A resource matches Git but is failing | Fix the workload. Syncing again does not help. See application health |
Stays Progressing | A failing probe, an incomplete rollout, or a LoadBalancer without an address | kubectl describe the Pod and Service |
Health is Unknown for a custom resource | No health check for the kind | Add a custom health check |
| Later waves start too early | Dependencies have no readiness probes, or the Application kind has no health check | Add probes and the argoproj.io_Application health customization |
| Sync never leaves an early wave | A resource in that wave never becomes healthy | Find and fix it |
Clusters, projects, and multi-tenancy
Section titled “Clusters, projects, and multi-tenancy”| Symptom | Likely cause | Fix |
|---|---|---|
argocd cluster add cannot connect | The context’s API address is not routable from where it runs | Use a kubeconfig with a reachable address. See cluster management |
Cluster status Unknown | No Application targets it yet | Normal until one does |
Applications Unknown with x509 errors in the controller log | Wrong or non-base64 caData | Replace it |
Unauthorized or Forbidden on the target | Expired token, or a missing binding | Issue a new token and check the ClusterRoleBinding |
| Unknown destination cluster | name or server matches no cluster Secret | Check spelling. Use one of the two |
| Cluster-scoped resources skipped | namespaces is set and clusterResources is not "true" | Set it, or remove the restriction |
... is not permitted in project | The repository, destination, or kind is not allowed | Add it to the AppProject |
| A developer sees no Applications | The group has no project role or global binding | Add the group to the role. See multi-tenancy and projects |
| A project cannot use a repository | The repository is scoped to another project | Use an unscoped one, or scope one to this project |
| An Application in another namespace is ignored | The namespace is not in application.namespaces, or not in the project’s sourceNamespaces | Enable it in both places |
Authentication and RBAC
Section titled “Authentication and RBAC”| Symptom | Likely cause | Fix |
|---|---|---|
| Signed in but sees nothing | No role binding and an empty policy.default | Bind a role. See accounts and RBAC |
permission denied for an action the role seems to allow | A deny matches, or the object form is wrong | argocd admin settings rbac can ..., and check <project>/<name> |
| SSO group policies have no effect | No g binding, or scopes omits the claim | Add the binding and set scopes |
invalid redirect_uri at the provider | The callback is not registered, or url is wrong | Register <url>/auth/callback or <url>/api/dex/callback. See single sign-on |
| Login succeeds but the user has no access | The groups claim is missing | Decode the ID token and check the claim |
Group names start with / | Keycloak sends the full path | Turn Full group path off |
| Login loops or returns 401 after a change | argocd-server holds stale settings | Restart it and clear cookies |
| CLI login hangs or the callback fails | The localhost callback is not allowed | Allow http://localhost:8085/auth/callback and use a public client with PKCE |
| Everyone locked out after typos | Failed-login throttling | Wait out the window |
| API call returns 401 | Token missing, expired, or without Bearer | Request a new token |
ApplicationSets and app-of-apps
Section titled “ApplicationSets and app-of-apps”| Symptom | Likely cause | Fix |
|---|---|---|
| No Applications created | The generator returned nothing, or the template is invalid | Check the controller logs and status conditions. See App-of-apps and ApplicationSets |
| Template renders empty values | A misspelled parameter | Enable goTemplateOptions: ["missingkey=error"] |
| A manual edit to a generated Application is overwritten | The controller owns the spec | Change the template, or use the create-only policy |
| Deleting an ApplicationSet removed workloads | Cascading deletion through finalizers | Set preserveResourcesOnDeletion: true first |
| Progressive sync does nothing | The feature is off, or the controller was not restarted | Enable it and restart |
Parent stays Progressing | A child never becomes healthy | Fix the child’s failing resource |
Monitoring and notifications
Section titled “Monitoring and notifications”| Symptom | Likely cause | Fix |
|---|---|---|
| Prometheus shows no Argo CD targets | The ServiceMonitor lacks the release label, or metrics are off | Set additionalLabels.release and enable metrics. See monitoring and notifications |
| No notification arrives | No subscription annotation, a typo, or the condition is false | Check the annotation, then argocd admin notifications trigger run |
| Delivery fails | Bad token, the bot is not in the channel, or the service is undefined | Check the controller logs |
| Duplicate messages | A flapping condition | Add oncePer |
| Messages link to the wrong host | argocdUrl is unset | Set it |
Performance and scale
Section titled “Performance and scale”| Symptom | Likely cause | Fix |
|---|---|---|
| Slow refresh after many commits to a monorepo | Every commit invalidates every Application’s cache | Add manifest-generate-paths and fully qualified revisions. See high availability and scaling |
| One controller shard is saturated | A heavy cluster hashed to it | Pin clusters to shards |
| Controller memory keeps growing | Large clusters with many cached objects | Shard, raise memory, and ignore noisy resource updates |
| The UI is unreachable during upgrades | A single API server replica | Run at least two |
| Applications refresh constantly | A resource rewrites itself, such as a status timestamp | Use ignoreResourceUpdates for that kind |
When to ask for help
Section titled “When to ask for help”Gather this before opening an issue or asking a colleague:
- The Argo CD version (
argocd version) and how it was installed. argocd app get <app> -o yaml, with secrets removed.- The relevant repo server and controller log lines, with timestamps.
- What changed just before the problem started, in Git or in the cluster.