argocd app sync fails with "comparison error": how to debug

TL;DR

A comparison error means ArgoCD could not diff git against the cluster: usually a malformed manifest in git, a resource type the cluster does not understand, or a templating failure (helm/kustomize) that produces invalid YAML. The comparison happens before any sync, so the cluster is untouched. Find the offending manifest with a local render.

The query

argocd app sync fails with "comparison error": how to debug

Use this when

• Sync fails during comparison, not during apply
• The diff view errors instead of showing differences
• After chart or kustomize changes
• New apps fail on first sync

Not for when

• Apps stuck OutOfSync (comparison works, convergence fails)
• Sync hook or wave failures
• Permission errors during apply

Steps

Step 1: Render the manifests locally

Run the same templating ArgoCD uses (helm template or kustomize build) against the git revision. Templating errors show up immediately and locally, with better error messages than the ArgoCD UI. Expected output: the render either succeeds (problem is elsewhere) or fails with the exact error.

Step 2: Validate the rendered YAML

Pipe the rendered output through a YAML validator and a Kubernetes schema check. Comparison errors often come from YAML that parses but is not valid Kubernetes (wrong apiVersion, bad indentation changing structure). Expected output: the invalid document identified by line and resource.

Step 3: Check for unknown resource types

If the manifests reference CRDs, confirm those CRDs exist in the target cluster. ArgoCD cannot compare a resource type the cluster does not know; the comparison fails instead of warning. Expected output: all referenced CRDs present in the cluster.

Step 4: Look at the repo-server logs

The ArgoCD repo-server logs show the comparison failure in detail: which file, which resource, what parse error. The UI summarizes; the logs specify. Expected output: the precise file and error from the server side.

Step 5: Fix, commit, and re-sync

Fix the manifest or template, commit, and trigger a refresh plus sync. Verify the comparison completes and the diff looks as expected before applying. Expected output: clean comparison, accurate diff, successful sync.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstb5JyLJJqo56082KMemJCw