# Argo CD Troubleshooting Common Issues: Component-Based Diagnostics and Solutions

> Troubleshoot common Argo CD issues by diagnosing failures in API Server, Repo Server, Application Controller, Redis, or Notification Engine using logs and configuration checks.

- Repository: [Argo Project/argo-cd](https://github.com/argoproj/argo-cd)
- Tags: how-to-guide
- Published: 2026-07-15

---

**Most Argo CD failures can be traced to one of five core components—API Server, Repo Server, Application Controller, Redis, or Notification Engine—by checking component-specific logs and validating RBAC, repository credentials, or resource tracking configuration.**

Argo CD is a declarative, GitOps continuous delivery tool that continuously monitors desired state in Git repositories and syncs them to Kubernetes clusters. Because its architecture separates concerns across independent pods communicating via gRPC and Redis, effective troubleshooting requires isolating the specific component where the error originates. This guide draws from the **argoproj/argo-cd** source code to provide concrete diagnostics for the most frequent failure modes.

## Component Architecture Overview

Understanding which pod handles which operation accelerates root-cause analysis. The source code defines these primary components:

| Component | Source File | Critical Function |
|-----------|-------------|-------------------|
| **API Server** | [`cmd/argocd-server/commands/argocd_server.go`](https://github.com/argoproj/argo-cd/blob/main/cmd/argocd-server/commands/argocd_server.go) | Exposes UI/CLI, validates requests, stores state in ConfigMaps/Secrets |
| **Repo Server** | [`reposerver/server.go`](https://github.com/argoproj/argo-cd/blob/main/reposerver/server.go) | Clones Git/Helm/OCI repos, renders manifests (Kustomize, Jsonnet, Helm) |
| **Application Controller** | [`controller/sync.go`](https://github.com/argoproj/argo-cd/blob/main/controller/sync.go), [`controller/state.go`](https://github.com/argoproj/argo-cd/blob/main/controller/state.go) | Diff live cluster state, drive sync operations, report health |
| **Redis** | [`controller/metrics/clustercollector.go`](https://github.com/argoproj/argo-cd/blob/main/controller/metrics/clustercollector.go) | Stores operation locks, health status, temporary tokens |
| **Notification Engine** | [`notification_controller/controller/controller_test.go`](https://github.com/argoproj/argo-cd/blob/main/notification_controller/controller/controller_test.go) | Sends alerts on sync failures and health degradation |

## Connectivity and Authentication Failures

### Cluster Connection Errors

If the Application Controller cannot reach a target cluster, verify the **RBAC permissions** for the `argocd-application-controller` service account. The controller requires a ClusterRole with sufficient permissions to read and write resources in the target namespaces. According to the [FAQ documentation](https://github.com/argoproj/argo-cd/blob/master/docs/faq.md), connection errors often manifest as "Unable to connect to cluster" messages in the controller logs.

Check the controller logs for TLS or authentication rejections:

```bash
kubectl logs -l app.kubernetes.io/name=argocd-application-controller -c manager -f

```

### Repository Access Failures

Authentication errors for Git, Helm, or OCI repositories surface in the **Repo Server** logs. The [`reposerver/server.go`](https://github.com/argoproj/argo-cd/blob/main/reposerver/server.go) logic handles credential validation during the clone phase. Common failures include expired SSH keys, invalid HTTPS tokens, or missing OCI credentials.

Validate stored credentials using the CLI:

```bash
argocd repo list
argocd repo get <REPO-URL>

```

These commands force a fetch operation and surface authentication errors directly from the Repo Server.

## Sync and Health Issues

### Persistent OutOfSync State

Applications showing **OutOfSync** status after successful syncs usually indicate **configuration drift** (manual cluster changes) or **resource tracking** misconfiguration. Argo CD supports multiple resource tracking strategies—label, annotation, or legacy—and mismatches cause the controller to lose ownership of live resources.

Review the [Resource Tracking documentation](https://github.com/argoproj/argo-cd/blob/master/docs/user-guide/resource_tracking.md) to verify your strategy matches the deployed resources.

### Sync Operation Failures

When sync operations fail, examine the [`controller/sync.go`](https://github.com/argoproj/argo-cd/blob/main/controller/sync.go) reconciliation loop and [`controller/state.go`](https://github.com/argoproj/argo-cd/blob/main/controller/state.go) diff logic. These files contain the core logic that generates detailed error messages about resource conflicts or validation failures.

View application-specific events and logs:

```bash
argocd app logs <APP>
argocd app diff <APP>

```

The diff command compares the live state against the desired state stored in Git, highlighting fields that prevent successful synchronization.

## Manifest Rendering Errors

Rendering failures for Kustomize, Helm, or Jsonnet occur entirely within the Repo Server. Errors like *"kustomize build failed"* or *"helm template error"* originate in the `util/kustomize` and `util/helm` code paths called by [`reposerver/server.go`](https://github.com/argoproj/argo-cd/blob/main/reposerver/server.go).

Ensure the correct tool versions are present. Argo CD bundles known versions of these binaries; custom plugins require matching binaries available in the Repo Server pod.

## Performance and High Availability Concerns

Heavy metric collection can degrade performance in large-scale deployments. The [`controller/metrics/clustercollector.go`](https://github.com/argoproj/argo-cd/blob/main/controller/metrics/clustercollector.go) logic continuously aggregates cluster state metrics. The [High Availability guide](https://github.com/argoproj/argo-cd/blob/master/docs/operator-manual/high_availability.md) recommends disabling the metrics collector when troubleshooting performance bottlenecks or during high-load sync operations.

## Notification Delivery Failures

Missing alerts typically stem from misconfigured webhook URLs or SMTP credentials in the Notification Engine. The [`notification_controller/controller/controller_test.go`](https://github.com/argoproj/argo-cd/blob/main/notification_controller/controller/controller_test.go) file defines the error handling logic for delivery attempts. Check the [Notification Troubleshooting guide](https://github.com/argoproj/argo-cd/blob/master/docs/operator-manual/notifications/troubleshooting.md) for a step-by-step configuration checklist.

## Essential Diagnostic Commands

Force a hard refresh and view real-time controller logs to isolate timing issues:

```bash
argocd app sync my-app --hard
kubectl logs -l app.kubernetes.io/name=argocd-application-controller -c manager -f

```

Inspect specific resource events in the target cluster:

```bash
kubectl describe <RESOURCE-TYPE> <RESOURCE-NAME> -n <NAMESPACE>

```

## Summary

- **Isolate the component first**: API Server (auth/UI), Repo Server (manifest generation), or Application Controller (sync logic).
- **Check RBAC and credentials**: Cluster connection errors require validating the `argocd-application-controller` ClusterRole; repository errors require checking SSH/HTTPS tokens in the Repo Server.
- **Investigate OutOfSync carefully**: Distinguish between configuration drift and resource tracking strategy mismatches.
- **Monitor Repo Server logs**: Rendering errors for Kustomize, Helm, or Jsonnet appear here before reaching the controller.
- **Disable metrics when troubleshooting performance**: As documented in the HA operator manual.

## Frequently Asked Questions

### Why is Argo CD unable to connect to my cluster?

This error usually indicates insufficient RBAC permissions for the `argocd-application-controller` service account or invalid TLS certificates. Verify that the ClusterRole bound to the controller includes permissions to read and write all resources managed by Argo CD. Check the controller logs for TLS handshake failures or authentication rejections.

### Why does my application stay OutOfSync after syncing?

OutOfSync states persist when live cluster resources drift from the Git-declared state due to manual edits, or when the **resource tracking** method (label, annotation, or legacy) does not match the strategy used by existing resources. Run `argocd app diff` to identify specific field-level drift, and consult the resource tracking documentation to align ownership markers.

### How do I debug repository authentication failures?

Repository errors surface in the Repo Server logs ([`reposerver/server.go`](https://github.com/argoproj/argo-cd/blob/main/reposerver/server.go)). Use `argocd repo get <REPO-URL>` to force a validation fetch that returns detailed authentication errors. Verify that SSH private keys, HTTPS tokens, or OCI registry credentials are correctly stored in Argo CD secret references and have not expired.

### Why are my Argo CD notifications not being sent to Slack or email?

Notification failures typically result from misconfigured webhook URLs, missing SMTP authentication, or incorrect trigger definitions in the Notification Engine configuration. The controller validates these settings against [`notification_controller/controller/controller_test.go`](https://github.com/argoproj/argo-cd/blob/main/notification_controller/controller/controller_test.go) logic. Review the notification troubleshooting documentation to verify service selectors and delivery service configurations.