# Troubleshooting Common Argo CD Deployment Issues: A Complete Guide for GitOps Operators

> Troubleshoot common Argo CD deployment issues. Learn to diagnose cluster connectivity, ConfigMap, and TLS errors using argocd admin CLI tools and ConfigMaps.

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

---

**Argo CD deployment issues typically stem from cluster connectivity failures, ConfigMap misconfigurations, or TLS certificate errors that you can diagnose using the `argocd admin` CLI tools and validate against the `argocd-cm` and `argocd-rbac-cm` ConfigMaps.**

When applications fail to sync or the UI becomes inaccessible in the **argoproj/argo-cd** repository, operators need a systematic approach to isolate whether the problem lies in network policies, credential storage, or Lua script customization. This guide covers the six dominant failure categories and the exact diagnostic commands used by the Argo CD maintainers to resolve them.

## Cluster Connectivity and Credential Failures

Applications stuck in an **OutOfSync** state or displaying *Unable to connect* errors usually indicate that the `argocd-application-controller` cannot reach the target cluster.

The controller stores kubeconfig data in Secrets and mounts them at runtime. When network policies block egress or the kubeconfig contains outdated certificates, the controller fails to reconcile desired state with live resources.

**Diagnose with the admin cluster command:**

```bash
argocd admin cluster kubeconfig https://<api-server-url> /tmp/kubeconfig \
  --namespace argocd

export KUBECONFIG=/tmp/kubeconfig
kubectl get pods -v 9

```

The `-v 9` flag exposes verbose authentication logs. If you see certificate verification or authorization errors, regenerate the cluster credentials in the `argocd` namespace and update the associated Secret.

## ConfigMap Misconfigurations in argocd-cm

Malformed Lua scripts or invalid YAML in the `argocd-cm` ConfigMap cause persistent diffing errors and incorrect health assessments. Argo CD stores **resource customizations**, **diffing ignore rules**, and **health check scripts** in this ConfigMap.

Validate the entire configuration before applying changes:

```bash
argocd admin settings validate

```

To test specific resource overrides without deploying to the cluster:

```bash
argocd admin settings resource-overrides ignore-differences ./deploy.yaml \
  --argocd-cm-path ./argocd-cm.yaml

```

This command parses your local [`argocd-cm.yaml`](https://github.com/argoproj/argo-cd/blob/main/argocd-cm.yaml) and reports syntax errors in `resource.customizations` blocks before they reach the server.

## TLS and mTLS Certificate Verification Errors

When the API server returns **403/401** errors or the UI fails to load entirely, inspect the TLS certificates mounted to the `argocd-server` and `argocd-repo-server` pods. Argo CD components use mutual TLS (mTLS) for inter-service communication; missing client certificates or mismatched CA bundles break this trust chain.

Verify that Secrets containing TLS data are correctly referenced in the Deployment manifests and that certificate expiration dates are current. The `argocd-server` logs (`kubectl logs deployment/argocd-server`) will explicitly flag certificate verification failures during handshake attempts.

## RBAC Policy Restrictions in argocd-rbac-cm

Users who cannot view applications or execute sync operations often face overly restrictive policies defined in the `argocd-rbac-cm` ConfigMap. Unlike Kubernetes RBAC, Argo CD maintains its own policy engine for GitOps-specific actions.

Key symptoms include:
- UI elements silently disappearing for specific users
- API calls returning **403 Forbidden** despite valid Kubernetes RBAC bindings
- Inability to execute custom resource actions

Validate policies using the administrative RBAC inspection tools. Ensure that Policy CSV rules include the correct `p, <user/group>, <resource>, <action>, <object>` patterns documented in [`docs/user-guide/rbac.md`](https://github.com/argoproj/argo-cd/blob/main/docs/user-guide/rbac.md).

## Resource Health and Custom Action Script Failures

Resources displaying **Unknown** health status or failing custom actions typically contain Lua script errors in the `resource.customizations.health` blocks of `argocd-cm`.

Test health checks locally:

```bash
argocd admin settings resource-overrides health ./deploy.yaml \
  --argocd-cm-path ./argocd-cm.yaml

```

List available actions to verify script registration:

```bash
argocd admin settings resource-overrides list-actions ./deploy.yaml \
  --argocd-cm-path ./argocd-cm.yaml

```

These commands execute the Lua scripts against your resource YAML without requiring a live cluster, catching nil reference errors or invalid return types before deployment.

## Sync Window and Wave Configuration Problems

Applications refusing to sync during scheduled maintenance windows or ignoring wave ordering indicate misconfigurations in `spec.syncWindows` or conflicting wave annotations. Argo CD evaluates sync windows against the application's destination namespace and cluster; mismatched selectors cause silent denials.

Validate window definitions using the `argocd` CLI:

```bash
argocd app get <app-name> -o yaml

```

Check that `kind`, `schedule`, and `duration` fields follow the cron expression format and that wave numbers in sync hooks progress monotonically from negative to positive values.

## Step-by-Step Troubleshooting Workflow

The Argo CD project recommends this sequential diagnostic approach:

1. **Validate settings** – Run `argocd admin settings validate` to ensure `argocd-cm` and `argocd-rbac-cm` contain syntactically correct YAML.

2. **Export and test cluster credentials** – Use `argocd admin cluster kubeconfig` to extract stored kubeconfigs and verify connectivity with `kubectl`.

3. **Inspect health and diff customizations** – Execute `argocd admin settings resource-overrides` against local manifests to verify Lua scripts load without runtime errors.

4. **Check TLS configuration** – Confirm certificates are valid, not expired, and correctly mounted to the `argocd-server` and `argocd-repo-server` Deployments.

5. **Review RBAC policies** – Audit `argocd-rbac-cm` to ensure users and service accounts possess `get`, `sync`, and `override` permissions required for their roles.

6. **Analyze application logs** – Check `argocd-application-controller` and `argocd-repo-server` logs for reconciliation errors after credentials and configuration are verified.

## Key Configuration Files and Documentation References

Understanding these source files accelerates root cause analysis:

- **[`docs/operator-manual/troubleshooting.md`](https://github.com/argoproj/argo-cd/blob/main/docs/operator-manual/troubleshooting.md)** – Central diagnostic guide containing admin commands and connectivity troubleshooting steps.

- **[`docs/operator-manual/installation.md`](https://github.com/argoproj/argo-cd/blob/main/docs/operator-manual/installation.md)** – Component manifest definitions for `argocd-server`, `argocd-application-controller`, and `argocd-dex`.

- **[`docs/user-guide/diffing.md`](https://github.com/argoproj/argo-cd/blob/main/docs/user-guide/diffing.md)** – Detailed specifications for `resource.customizations` and ignore-difference configurations.

- **[`docs/user-guide/health.md`](https://github.com/argoproj/argo-cd/blob/main/docs/user-guide/health.md)** – Reference for built-in health checks and custom Lua script requirements.

- **[`docs/user-guide/rbac.md`](https://github.com/argoproj/argo-cd/blob/main/docs/user-guide/rbac.md)** – Policy CSV syntax and permission scopes for the `argocd-rbac-cm` ConfigMap.

- **[`manifests/base/argocd-cm.yaml`](https://github.com/argoproj/argo-cd/blob/main/manifests/base/argocd-cm.yaml)** – Base ConfigMap manifest storing resource overrides, diffing rules, and health scripts.

- **[`manifests/base/argocd-rbac-cm.yaml`](https://github.com/argoproj/argo-cd/blob/main/manifests/base/argocd-rbac-cm.yaml)** – Base RBAC ConfigMap defining default policies and role mappings.

## Summary

- **Cluster connectivity issues** manifest as OutOfSync applications and require validating exported kubeconfigs with `argocd admin cluster kubeconfig`.

- **ConfigMap errors** in `argocd-cm` break diffing and health assessments; validate offline using `argocd admin settings validate`.

- **TLS/mTLS failures** between components cause 403/401 errors and require verifying certificate mounts in server Deployments.

- **RBAC restrictions** in `argocd-rbac-cm` silently hide UI elements or block API access independently of Kubernetes RBAC.

- **Lua script errors** produce Unknown health statuses; test locally with `argocd admin settings resource-overrides` commands.

- **Sync window misconfigurations** prevent automated syncs when cron expressions or wave numbers contain syntax errors.

## Frequently Asked Questions

### Why does Argo CD show "Unable to connect" for managed clusters?

The `argocd-application-controller` cannot authenticate to the target Kubernetes API server. Export the stored kubeconfig using `argocd admin cluster kubeconfig`, then run `kubectl get pods -v 9` to identify certificate, network policy, or credential issues without modifying the Argo CD installation.

### How do I validate Argo CD ConfigMap changes before applying them?

Use `argocd admin settings validate` to check `argocd-cm` and `argocd-rbac-cm` syntax. For resource-specific customizations, run `argocd admin settings resource-overrides` with the `--argocd-cm-path` flag to test Lua health scripts and diffing rules against local YAML files without deploying to the cluster.

### What causes custom resource health checks to return "Unknown"?

Lua scripts defined in `argocd-cm` under `resource.customizations.health` likely contain syntax errors or nil pointer exceptions. Debug these by executing `argocd admin settings resource-overrides health <resource.yaml> --argocd-cm-path ./argocd-cm.yaml` to run the script against your resource definition locally and view stack traces.

### Where are Argo CD RBAC policies stored and how do they differ from Kubernetes RBAC?

Argo CD maintains its own policy engine in the `argocd-rbac-cm` ConfigMap, separate from Kubernetes RBAC. These policies control GitOps-specific actions like application syncing and resource overriding using a Policy CSV format. Kubernetes RBAC governs API server access, while Argo CD RBAC governs the UI and CLI application management layer.