How to fix sync wave error in Kubernetes
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.
Quick fix
Fixes sync wave error
metadata:
annotations:
argocd.argoproj.io/sync-wave: "0"- Understand sync wave concept
- Add sync-wave annotations to resources
- Use PreSync and PostSync hooks for sequential operations
- Ensure hooks wait for completion
metadata:annotations:argocd.argoproj.io/sync-wave: "0"sync wave error
What this error means
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.
Typical symptoms
- Resources deploy out of order despite sync-wave annotations
- Jobs or hooks in earlier waves do not complete before later waves
- Application appears stuck during sync operation
- Resources fail to create due to missing prerequisites from earlier waves
- Database migrations fail because Job finishes after Deployment
- Sync wave annotations are ignored and all resources apply simultaneously
- Pre-sync hooks do not run before resource deployment
- Hooks fail silently without blocking resource deployment
Common causes
- Sync wave annotation not properly formatted or specified
- Hook does not have appropriate argocd.argoproj.io/hook annotation
- Job or Pod does not complete before next wave starts
- No synchronization mechanism to wait for earlier waves
- Hook type is incorrect or hook condition not met
- Resources in same wave have inter-dependencies
- PreSync hook fails but sync continues
- Wave configured but sync policy does not respect waves
How to fix "sync wave error"
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 DeleteAdvanced notes
For 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.
Frequently asked questions
- What does "sync wave error" mean?
- 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.
- How do I fix "sync wave error"?
- 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.
- What causes "sync wave error"?
- Sync wave annotation not properly formatted or specified Hook does not have appropriate argocd.argoproj.io/hook annotation Job or Pod does not complete before next wave starts
- Is the "sync wave error" error serious?
- It is a medium-severity error โ more of a blocker than a risk. The steps above resolve it.
Official resources & further reading
- ๐Kubernetes Official Documentation
- ๐ArgoCD Sync Waves(Official Docs)
- ๐Sync Waves and Hooks Tutorial(Official Docs)
- ๐Understanding Sync Waves(Official Docs)