Sync wave errors occur when resources with wave annotations do not apply in the expected order. Fix by properly configuring argocd.argoproj.io/sync-wave annotations and ensuring hooks complete before dependent resources.
Sync waves in ArgoCD allow you to control the order in which resources are deployed. A sync wave error occurs when resources fail to apply in the correct sequence, often because earlier-wave resources have not finished deploying or hooks have not completed. This prevents later-wave resources from being created in the correct order.
Sync waves order resource deployment in ArgoCD. Resources without annotation default to wave 0. All resources in wave 0 deploy first, then wave 1, etc. You can use negative waves to deploy before wave 0:
metadata:
annotations:
argocd.argoproj.io/sync-wave: "0"Organize resources into waves based on dependencies:
# Wave 1: Create namespace and RBAC
apiVersion: v1
kind: Namespace
metadata:
name: myapp
annotations:
argocd.argoproj.io/sync-wave: "1"
---
# Wave 2: Database migrations
apiVersion: batch/v1
kind: Job
metadata:
annotations:
argocd.argoproj.io/sync-wave: "2"
---
# Wave 3: Application deployment
apiVersion: apps/v1
kind: Deployment
metadata:
annotations:
argocd.argoproj.io/sync-wave: "3"Configure hooks to run at specific points:
apiVersion: batch/v1
kind: Job
metadata:
name: db-migrate
annotations:
argocd.argoproj.io/hook: PreSync
argocd.argoproj.io/hook-phase: Sync
argocd.argoproj.io/sync-wave: "0"
spec:
template:
spec:
containers:
- name: migrate
image: mydb:latest
command: ["./migrate.sh"]
restartPolicy: NeverConfigure hook deletion policy to wait for completion:
metadata:
annotations:
argocd.argoproj.io/hook-delete-policy: HookSucceeded,HookFailedOptions are: HookSucceeded (delete on success), HookFailed (delete on failure), or both.
Verify annotations in your manifests:
kubectl get deployment -o yaml | grep -A 2 "sync-wave"Ensure annotations are under metadata.annotations, not elsewhere.
Check the sync operation logs to see wave progression:
kubectl logs -n argocd -l app.kubernetes.io/name=argocd-application-controllerLook for "applying wave X" messages to verify correct order.
Resources in the same wave deploy simultaneously. If one depends on another, put them in different waves:
# Wrong - same wave
metadata:
annotations:
argocd.argoproj.io/sync-wave: "1"
# Correct - sequential waves
metadata:
annotations:
argocd.argoproj.io/sync-wave: "1" # ConfigMap
---
metadata:
annotations:
argocd.argoproj.io/sync-wave: "2" # Pod using ConfigMapControl when hooks execute relative to resource sync:
annotations:
argocd.argoproj.io/hook: PreSync # Before any resources
argocd.argoproj.io/hook-phase: Sync # Can be Sync or DeleteFor complex applications, consider using Kustomize or Helm to manage wave ordering programmatically. Waves only order deployment within a single Application - use App of Apps pattern for multi-application dependencies. Monitor hook execution time to avoid timeouts in later waves. Test your wave configuration with --dry-run before deploying to production. Remember that waves do not work across Applications, only within them.
No subnets found for EKS cluster
How to fix "eks subnet not found" in Kubernetes
unable to compute replica count
How to fix "unable to compute replica count" in Kubernetes HPA
error: context not found
How to fix "error: context not found" in Kubernetes
default backend - 404
How to fix "default backend - 404" in Kubernetes Ingress
serviceaccount cannot list resource
How to fix "serviceaccount cannot list resource" in Kubernetes