How to fix sync wave error in Kubernetes

KubernetesINTERMEDIATEMEDIUMUpdated Dec 6, 2025ยท 150 views

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"
  1. Understand sync wave concept
  2. Add sync-wave annotations to resources
  3. Use PreSync and PostSync hooks for sequential operations
  4. Ensure hooks wait for completion
kubernetes โ€” error
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

  1. Sync wave annotation not properly formatted or specified
  2. Hook does not have appropriate argocd.argoproj.io/hook annotation
  3. Job or Pod does not complete before next wave starts
  4. No synchronization mechanism to wait for earlier waves
  5. Hook type is incorrect or hook condition not met
  6. Resources in same wave have inter-dependencies
  7. PreSync hook fails but sync continues
  8. Wave configured but sync policy does not respect waves

How to fix "sync wave error"

1Understand sync wave concept

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:

yaml
metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "0"
2Add sync-wave annotations to resources

Organize resources into waves based on dependencies:

yaml
# 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"
3Use PreSync and PostSync hooks for sequential operations

Configure hooks to run at specific points:

yaml
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: Never
4Ensure hooks wait for completion

Configure hook deletion policy to wait for completion:

yaml
metadata:
  annotations:
    argocd.argoproj.io/hook-delete-policy: HookSucceeded,HookFailed

Options are: HookSucceeded (delete on success), HookFailed (delete on failure), or both.

5Check sync wave annotations are correctly applied

Verify annotations in your manifests:

bash
kubectl get deployment -o yaml | grep -A 2 "sync-wave"

Ensure annotations are under metadata.annotations, not elsewhere.

6Review ArgoCD application sync logs

Check the sync operation logs to see wave progression:

bash
kubectl logs -n argocd -l app.kubernetes.io/name=argocd-application-controller

Look for "applying wave X" messages to verify correct order.

7Avoid inter-dependencies within the same wave

Resources in the same wave deploy simultaneously. If one depends on another, put them in different waves:

yaml
# 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 ConfigMap
8Use sync phases to control hook timing

Control when hooks execute relative to resource sync:

yaml
annotations:
  argocd.argoproj.io/hook: PreSync  # Before any resources
  argocd.argoproj.io/hook-phase: Sync  # Can be Sync or Delete

Advanced 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