Troubleshooting & Errors

A quick error lookup table and a repeatable debugging routine for when a workflow fails.

The five-command routine

argo get -n NS WORKFLOW
argo logs -n NS WORKFLOW
kubectl -n NS describe pod POD
kubectl -n NS get events --sort-by=.lastTimestamp
kubectl -n argo logs deploy/workflow-controller --tail=200

Run them in order. The first tells you which node failed and why; the second shows what your code printed; the third and fourth reveal scheduling, image and quota problems; the fifth exposes controller-level issues such as permissions or watched namespaces.

Error lookup

Message containsLikely causeFirst fix
workflowtaskresults … forbiddenExecutor RBAC missingBind the executor role to the service account
Unable to resolveUndeclared input or wrong step/task nameDeclare inputs; reference earlier steps only
dependency cycleDAG tasks depend on each otherRemove an edge; check in the visualizer
OOMKilled / exit 137Memory limit exceededRaise the limit or reduce memory use
ImagePullBackOffBad tag or missing pull secretVerify the image; add imagePullSecrets
exceeded quotaNamespace ResourceQuota fullLower parallelism or raise the quota
configure artifact storageNo artifact repositoryAdd one to the controller ConfigMap
longer than maximum allowed sizeWorkflow status too largeEnable node status offloading
unknown field "schedule"v4 removed the fieldUse the schedules list

Prevent the next failure

For detailed explanations of more than twenty errors, read the full troubleshooting guide.

Guides

Recommended tools