How to fix ArgoCD hook failed in Kubernetes

KubernetesINTERMEDIATEHIGH

ArgoCD sync operations hang or fail when resource hooks (PreSync, PostSync, Sync, SyncFail) encounter errors, timeouts, or resource conflicts. Causes include Jobs getting deleted before completion, immutable field errors, hook timeout mismatches, or unfinished hook resources. Fix by adjusting ttlSecondsAfterFinished, using proper delete policies, implementing health checks, and debugging hook resource status.

What this error means

ArgoCD hooks are Kubernetes resources (Jobs, Pods, etc.) annotated with argocd.argoproj.io/hook that run before, during, or after a sync operation. When a hook fails, times out, or becomes stuck in a pending state, the entire sync operation is blocked. This typically happens because hook resources are not completing successfully, ArgoCD cannot detect completion, or subsequent hook phases cannot proceed due to resource conflicts. Understanding hook lifecycle and deletion policies is critical to debugging sync failures.

How to fix "ArgoCD hook failed"

1Check hook resource status in ArgoCD UI

Navigate to your Application > Sync Result tab to see hook execution status:

bash

# Or query via CLI
kubectl get job -A | grep -E "presync|postsync|sync-hook"
kubectl describe job <hook-job-name> -n <namespace>

Look for: Completed/Failed/Pending/Unknown states. Check job logs:

bash

kubectl logs job/<hook-job-name> -n <namespace>

2Set proper ttlSecondsAfterFinished on hook Jobs

Prevent Jobs from being deleted before ArgoCD detects completion:

yaml

apiVersion: batch/v1
kind: Job
metadata:
  name: presync-migration
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: BeforeHookCreation,HookSucceeded
spec:
  ttlSecondsAfterFinished: 60  # Allow 60 seconds for detection
  backoffLimit: 1
  template:
    spec:
      containers:
      - name: migrator
        image: my-migration:latest
        command: ["./migrate.sh"]
      restartPolicy: Never

Minimum recommended: 60 seconds. Higher values if hook takes longer to complete.

3Apply correct hook-delete-policy

Delete policies control when hook resources are cleaned up:

yaml

metadata:
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: BeforeHookCreation,HookSucceeded

Delete policies:
- BeforeHookCreation: Delete resource before creating new one (prevents immutable field errors)
- HookSucceeded: Delete after hook succeeds
- HookFailed: Delete if hook fails

Recommended for Jobs: BeforeHookCreation,HookSucceeded. Do NOT use alone without one of the completion policies.

4Use correct hook type for your use case

Ensure hook timing aligns with your workflow:

yaml

# Run before any resources sync
argocd.argoproj.io/hook: PreSync

# Run after main resources synced
argocd.argoproj.io/hook: PostSync

# Run during main sync (between PreSync and PostSync)
argocd.argoproj.io/hook: Sync

# Run only if sync fails
argocd.argoproj.io/hook: SyncFail

Common pattern: PreSync for schema migrations, Sync for main deployment, PostSync for tests/verification.

5Check hook resource health and timeouts

Verify the hook resource itself is healthy:

bash

kubectl get job <job-name> -n <namespace> -o jsonpath="{.status}"

# Check pod logs for failures
kubectl get pods -l job-name=<job-name> -n <namespace>
kubectl logs <pod-name> -n <namespace>

# Check for timeout issues
kubectl describe job <job-name> -n <namespace> | grep -i "timeout\|backoff"

Ensure:
- Job completes successfully (Succeeded=1)
- Pod exits with code 0
- Active pods count reaches 0
- No backoff warnings

6Enable ServerSideApply for immutable field errors

If hooks fail with "Field is immutable" errors:

yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
spec:
  syncPolicy:
    syncOptions:
    - ServerSideApply=true
    - ApplyOutOfSyncOnly=true

ServerSideApply allows updating objects without recreating them. Combined with ApplyOutOfSyncOnly, prevents unnecessary hook re-runs.

7Verify hook waves and dependencies

Use sync waves to control hook execution order:

yaml

metadata:
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/sync-wave: "0"  # Runs first
    argocd.argoproj.io/hook-delete-policy: BeforeHookCreation,HookSucceeded
---
metadata:
  annotations:
    argocd.argoproj.io/hook: Sync
    argocd.argoproj.io/sync-wave: "1"  # Runs after wave 0

Waves ensure hooks complete before dependent resources deploy. Default wave is 0.

How to fix ArgoCD hook failed in Kubernetes

What this error means

Typical symptoms

Common causes

How to fix "ArgoCD hook failed"

Advanced notes

Related errors

Official resources & further reading