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.
Fixes sync wave error
metadata:
annotations:
argocd.argoproj.io/sync-wave: "0"metadata:annotations:argocd.argoproj.io/sync-wave: "0"sync wave error
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.