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 contains | Likely cause | First fix |
|---|---|---|
workflowtaskresults … forbidden | Executor RBAC missing | Bind the executor role to the service account |
Unable to resolve | Undeclared input or wrong step/task name | Declare inputs; reference earlier steps only |
dependency cycle | DAG tasks depend on each other | Remove an edge; check in the visualizer |
OOMKilled / exit 137 | Memory limit exceeded | Raise the limit or reduce memory use |
ImagePullBackOff | Bad tag or missing pull secret | Verify the image; add imagePullSecrets |
exceeded quota | Namespace ResourceQuota full | Lower parallelism or raise the quota |
configure artifact storage | No artifact repository | Add one to the controller ConfigMap |
longer than maximum allowed size | Workflow status too large | Enable node status offloading |
unknown field "schedule" | v4 removed the field | Use the schedules list |
Prevent the next failure
- Validate every manifest before submitting with the YAML validator or
argo lint. - Score manifests with the configuration checker to catch missing deadlines and resources.
- Normalise indentation with the YAML formatter to avoid parsing surprises.
For detailed explanations of more than twenty errors, read the full troubleshooting guide.
Guides
Troubleshooting & ErrorsHow Do You Fix Common Argo Workflows Errors?
Diagnose and fix common Argo Workflows errors — RBAC and service accounts, pending pods, OOMKilled, image pulls, artifacts, parameter resolution, DAG cycles, UI login, CronWorkflows and controller issues.
Kubernetes IntegrationHow Does Argo Workflows Integrate With Kubernetes?
How Argo Workflows integrates with Kubernetes — service accounts, executor RBAC, namespaces, resource requests, scheduling, volumes, secrets, network policies and multi-tenant security.
Workflow AutomationHow Is an Argo Workflows YAML File Structured?
Understand every important field in Argo Workflows YAML — metadata, spec, templates, inputs, outputs, variables, expressions, retries, deadlines, garbage collection and synchronisation.