Skip to content
Documentation Background

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.


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?"]
  1. Read the Application’s status and conditions. They name the failing stage most of the time.

    Terminal window
    argocd app get catalog-api
    kubectl get application catalog-api -n argocd -o jsonpath='{.status.conditions}'

    A ComparisonError points at the repository or rendering. A sync failure shows the apply error and the resource that caused it.

  2. 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 to
    argocd app manifests catalog-api --source live
    argocd app diff catalog-api
  3. 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
  4. 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-server
    kubectl logs -n argocd statefulset/argocd-application-controller
    kubectl logs -n argocd deploy/argocd-server

    Raise detail temporarily with controller.log.level, reposerver.log.level, or server.log.level set to debug in argocd-cmd-params-cm, then restart the component. Return it to info afterwards.

  5. Check the target cluster. Many sync failures are Kubernetes errors, so kubectl describe on the failing resource and kubectl get events -n <namespace> often finish the investigation.


SymptomLikely causeFix
metadata.annotations: Too long on installClient-side apply cannot store the ApplicationSet CRDApply with --server-side --force-conflicts. See installation
Helm install fails with “already exists”A manifest-based install is still presentRemove it and the argocd namespace, then reinstall
Redis HA Pods stay PendingFewer than three nodesAdd nodes or use the non-HA topology. See high availability
Browser reports too many redirectsThe gateway terminated TLS while Argo CD still redirects to HTTPSSet server.insecure: "true" in argocd-cmd-params-cm
404 from the gateway for the Argo CD hostNo route matches the Host, or the ingress class is wrongCheck the hostname, class or parentRefs, and DNS
UI works but the CLI failsThe proxy does not pass gRPCLog in with --grpc-web. See Web UI and CLI
x509: certificate signed by unknown authority from the CLISelf-signed or private-CA certificate on the serverInstall a trusted certificate, or use --insecure while testing
A ConfigMap change has no effectThe ConfigMap lacks the app.kubernetes.io/part-of: argocd label, or a launch parameter needs a restartAdd the label, then restart the component. See declarative configuration
A repository or cluster Secret is ignoredWrong or missing argocd.argoproj.io/secret-type label, or wrong namespaceFix the label and apply the Secret in the Argo CD namespace

SymptomLikely causeFix
authentication requiredNo credentials, an expired token, or the wrong usernameUpdate the credentials. --upsert overwrites. See TLS and repository credentials
x509: certificate signed by unknown authority adding a repositoryThe Git host uses a private CAargocd cert add-tls <host> with the CA chain
SSH host key verification failedThe host key is not in argocd-ssh-known-hosts-cmssh-keyscan the host and add it with argocd cert add-ssh
SSH key rejectedA passphrase on the key, or the deploy key is on the wrong repositoryUse a key without a passphrase, registered on the right repository
Redirect with HTTP 301The URL lacks the .git suffix the host requiresUse the .git form
A new repository ignores the credential templateThe URL prefix does not match, or the repository has its own credentialsCheck the prefix and remove per-repository credentials
Git host rate-limits Argo CDPolling interval too short for the number of repositoriesLengthen timeout.reconciliation and use webhooks. See CI integration and webhooks
A pushed change takes two to three minutes to appearNo webhook, so the poll found itConfigure the webhook
Webhook delivery fails with 400 or a signature errorContent type is not application/json, or the secret differsFix the content type and compare the secret in argocd-secret
Webhook arrives but nothing refreshesThe event’s repository URL differs from the Application’s repoURLMatch the URL form, including .git and HTTPS vs SSH

SymptomLikely causeFix
A chart or plugin change is not picked upThe cached manifests are still validHard refresh. See CI integration and webhooks
A Helm value is ignoredA higher-precedence source overrides itCheck parameters and valuesObject. See rendering tools
A Kustomize directory deploys as plain filesNo kustomization.yaml at the Application’s pathPoint path at the directory that has it
Kustomize cannot inflate a Helm chart--enable-helm is not setSet kustomize.buildOptions or use a plugin, then restart. See extending Argo CD
OCI chart not foundrepoURL includes oci://, or no registry credentialsRemove the scheme and add credentials
Context deadline exceededManifest generation exceeds the timeoutRaise the repo server timeouts, and scale or tune the repo server
Repo server restarts with out-of-memory killsToo many concurrent generationsLower --parallelismlimit or raise memory
Plugin sidecar crash-loops or the plugin is never foundWrong command, user, plugin.yaml path, or nameCheck the three sidecar requirements and the sidecar logs
An Application is pruned empty after a plugin failureA pipe in generate hid the errorUse set -o pipefail

SymptomLikely causeFix
A new Application is OutOfSync and nothing deploysManual sync is the defaultSync it, or enable automated sync. See sync policies
A removed manifest still runsprune is offEnable prune, or sync with pruning
Auto-sync does not retry after a failureOne attempt per commit and parameter setPush a new commit, sync manually, or add retry
Auto-prune refuses to runThe source renders zero resourcesConfirm that is intended, then set allowEmpty: true
Sync fails for a custom resource kindThe CRD is created in the same syncAdd SkipDryRunOnMissingResource=true and a retry policy
Sync fails because the namespace is missingThe namespace was never createdAdd CreateNamespace=true
metadata.annotations: Too long on a resourceExceeds the client-side apply limitUse ServerSideApply=true
Sync is rejected for repository or destinationThe AppProject does not allow itAdjust 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 deletionInspect the hook. See phases, hooks, and waves
Nothing deployed after a failed syncA PreSync hook failed, which halts the syncFix the hook and sync again
A hook Job does not run againThe old Job still existsSet hook-delete-policy: BeforeHookCreation
Hooks did not runThe sync was a selective syncRun a full sync
Rollback is rejectedAutomated sync is enabledDisable it, or revert in Git
Pipeline sync rejectedThe token’s role lacks sync or override, or automated sync is onFix the role. See CI integration and webhooks
Sync fails after enabling impersonationNo matching destinationServiceAccounts entry, or the service account is missingAdd the entry and create the account. See commit signing and impersonation
Application blocked about an unsigned revisionThe target commit is not signed by an allowed keySign the commit, or fix the policy keys
Application stuck deletingA cascading delete waits on a resource that cannot be removedFix that resource. See Applications

SymptomLikely causeFix
OutOfSync right after a successful syncSomething mutates the object after applyargocd app diff, then add ignoreDifferences. See diffing and ignore rules
A field is ignored in the diff but overwritten by syncThe rule applies only to comparisonAdd RespectIgnoreDifferences=true
An operator-created resource keeps the app OutOfSyncIt is extraneous in the live stateAnnotate the triggering manifest with IgnoreExtraneous
A JSON pointer never matchesA key contains /Write it as ~1
Synced but DegradedA resource matches Git but is failingFix the workload. Syncing again does not help. See application health
Stays ProgressingA failing probe, an incomplete rollout, or a LoadBalancer without an addresskubectl describe the Pod and Service
Health is Unknown for a custom resourceNo health check for the kindAdd a custom health check
Later waves start too earlyDependencies have no readiness probes, or the Application kind has no health checkAdd probes and the argoproj.io_Application health customization
Sync never leaves an early waveA resource in that wave never becomes healthyFind and fix it

SymptomLikely causeFix
argocd cluster add cannot connectThe context’s API address is not routable from where it runsUse a kubeconfig with a reachable address. See cluster management
Cluster status UnknownNo Application targets it yetNormal until one does
Applications Unknown with x509 errors in the controller logWrong or non-base64 caDataReplace it
Unauthorized or Forbidden on the targetExpired token, or a missing bindingIssue a new token and check the ClusterRoleBinding
Unknown destination clustername or server matches no cluster SecretCheck spelling. Use one of the two
Cluster-scoped resources skippednamespaces is set and clusterResources is not "true"Set it, or remove the restriction
... is not permitted in projectThe repository, destination, or kind is not allowedAdd it to the AppProject
A developer sees no ApplicationsThe group has no project role or global bindingAdd the group to the role. See multi-tenancy and projects
A project cannot use a repositoryThe repository is scoped to another projectUse an unscoped one, or scope one to this project
An Application in another namespace is ignoredThe namespace is not in application.namespaces, or not in the project’s sourceNamespacesEnable it in both places

SymptomLikely causeFix
Signed in but sees nothingNo role binding and an empty policy.defaultBind a role. See accounts and RBAC
permission denied for an action the role seems to allowA deny matches, or the object form is wrongargocd admin settings rbac can ..., and check <project>/<name>
SSO group policies have no effectNo g binding, or scopes omits the claimAdd the binding and set scopes
invalid redirect_uri at the providerThe callback is not registered, or url is wrongRegister <url>/auth/callback or <url>/api/dex/callback. See single sign-on
Login succeeds but the user has no accessThe groups claim is missingDecode the ID token and check the claim
Group names start with /Keycloak sends the full pathTurn Full group path off
Login loops or returns 401 after a changeargocd-server holds stale settingsRestart it and clear cookies
CLI login hangs or the callback failsThe localhost callback is not allowedAllow http://localhost:8085/auth/callback and use a public client with PKCE
Everyone locked out after typosFailed-login throttlingWait out the window
API call returns 401Token missing, expired, or without Bearer Request a new token

SymptomLikely causeFix
No Applications createdThe generator returned nothing, or the template is invalidCheck the controller logs and status conditions. See App-of-apps and ApplicationSets
Template renders empty valuesA misspelled parameterEnable goTemplateOptions: ["missingkey=error"]
A manual edit to a generated Application is overwrittenThe controller owns the specChange the template, or use the create-only policy
Deleting an ApplicationSet removed workloadsCascading deletion through finalizersSet preserveResourcesOnDeletion: true first
Progressive sync does nothingThe feature is off, or the controller was not restartedEnable it and restart
Parent stays ProgressingA child never becomes healthyFix the child’s failing resource

SymptomLikely causeFix
Prometheus shows no Argo CD targetsThe ServiceMonitor lacks the release label, or metrics are offSet additionalLabels.release and enable metrics. See monitoring and notifications
No notification arrivesNo subscription annotation, a typo, or the condition is falseCheck the annotation, then argocd admin notifications trigger run
Delivery failsBad token, the bot is not in the channel, or the service is undefinedCheck the controller logs
Duplicate messagesA flapping conditionAdd oncePer
Messages link to the wrong hostargocdUrl is unsetSet it

SymptomLikely causeFix
Slow refresh after many commits to a monorepoEvery commit invalidates every Application’s cacheAdd manifest-generate-paths and fully qualified revisions. See high availability and scaling
One controller shard is saturatedA heavy cluster hashed to itPin clusters to shards
Controller memory keeps growingLarge clusters with many cached objectsShard, raise memory, and ignore noisy resource updates
The UI is unreachable during upgradesA single API server replicaRun at least two
Applications refresh constantlyA resource rewrites itself, such as a status timestampUse ignoreResourceUpdates for that kind

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.