argoproj/argo-workflows · error

failed to parse WorkflowTemplate: %w

Error message

failed to parse WorkflowTemplate: %w

What it means

When the document's kind is WorkflowTemplate, convertDocument unmarshals into convert.LegacyWorkflowTemplate to migrate singular mutex/semaphore fields to plural. A typed-unmarshal failure yields this error with the underlying yaml reason wrapped.

Source

Thrown at cmd/argo/commands/convert.go:117

	switch typeMeta.Kind {
	case wf.CronWorkflowKind:
		var legacy convert.LegacyCronWorkflow
		if err := yaml.Unmarshal(data, &legacy); err != nil {
			return fmt.Errorf("failed to parse CronWorkflow: %w", err)
		}
		converted = legacy.ToCurrent()

	case wf.WorkflowKind:
		var legacy convert.LegacyWorkflow
		if err := yaml.Unmarshal(data, &legacy); err != nil {
			return fmt.Errorf("failed to parse Workflow: %w", err)
		}
		converted = legacy.ToCurrent()

	case wf.WorkflowTemplateKind:
		var legacy convert.LegacyWorkflowTemplate
		if err := yaml.Unmarshal(data, &legacy); err != nil {
			return fmt.Errorf("failed to parse WorkflowTemplate: %w", err)
		}
		converted = legacy.ToCurrent()

	case wf.ClusterWorkflowTemplateKind:
		var legacy convert.LegacyClusterWorkflowTemplate
		if err := yaml.Unmarshal(data, &legacy); err != nil {
			return fmt.Errorf("failed to parse ClusterWorkflowTemplate: %w", err)
		}
		converted = legacy.ToCurrent()

	default:
		// Unknown type - pass through unchanged
		// Re-parse as generic map to preserve structure
		var generic map[string]any
		if err := yaml.Unmarshal(data, &generic); err != nil {
			return fmt.Errorf("failed to parse unknown kind %s: %w", typeMeta.Kind, err)
		}
		converted = generic

View on GitHub (pinned to 35bff19146)

Solutions

1. Fix the field named in the wrapped yaml error (expected type vs actual)
2. Run `argo lint` to validate the WorkflowTemplate schema independently of conversion
3. Confirm apiVersion/kind match the body contents (kind: WorkflowTemplate with Workflow-shaped body will fail)
4. Convert the file document-by-document if it is multi-doc to isolate the failing template

Example fix

// before (copy-paste mistake)
kind: WorkflowTemplate
spec:
  schedule: "0 0 * * *"
// after
kind: WorkflowTemplate
spec:
  templates: []

yq -e 'select(.kind == "WorkflowTemplate") | .spec.templates | type == "seq"' file.yaml \
  || echo 'WorkflowTemplate spec.templates must be a list'

if ! argo convert "$f" 2>err; then
  grep 'failed to parse WorkflowTemplate' err && echo 'verify kind matches body shape and field types'
fi

When it happens

Trigger: `argo convert` on a WorkflowTemplate whose body mismatches the legacy struct — e.g. `templates` not a list, `arguments`/`parameters` with wrong value types, or a WorkflowTemplate body accidentally holding CronWorkflow fields.

Common situations: Templates refactored by copy-paste between kinds (CronWorkflow fields left inside a WorkflowTemplate); Helm/Kustomize patches injecting wrong types; multi-doc manifests where a kind header was edited but the body was not.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• failed to parse TypeMeta: %w
• failed to parse CronWorkflow: %w
• failed to parse Workflow: %w
• no workflow found in given files
• unknown output mode: %s

AI-assisted analysis of argoproj/argo-workflows@35bff19146 (2026-09-03). Data as JSON: /api/errors/40aa53b260274917. Report an issue: GitHub.