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

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:

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:

argocd admin settings validate

To test specific resource overrides without deploying to the cluster:

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

This command parses your local 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.

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:

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

List available actions to verify script registration:

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:

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 – Central diagnostic guide containing admin commands and connectivity troubleshooting steps.

• docs/operator-manual/installation.md – Component manifest definitions for argocd-server, argocd-application-controller, and argocd-dex.

• docs/user-guide/diffing.md – Detailed specifications for resource.customizations and ignore-difference configurations.

• docs/user-guide/health.md – Reference for built-in health checks and custom Lua script requirements.

• docs/user-guide/rbac.md – Policy CSV syntax and permission scopes for the argocd-rbac-cm ConfigMap.

• manifests/base/argocd-cm.yaml – Base ConfigMap manifest storing resource overrides, diffing rules, and health scripts.

• 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}