argoproj/argo-workflows · error

failed to parse Workflow

Error message

failed to parse Workflow: %w

What it means

When the document's kind is Workflow, convertDocument unmarshals into convert.LegacyWorkflow to convert singular mutex/semaphore fields to plural. A failure here means the body could not be decoded into the legacy Workflow struct, and the underlying yaml error is wrapped in this message.

Solutions

1. Fix the field flagged in the wrapped yaml error (path and expected type are usually included)
2. Run `argo lint` on the file for authoritative schema errors
3. Check that legacy singular fields (sync via semaphore/mutex) are shaped as the legacy struct expects before conversion
4. Convert documents one at a time in multi-doc files to pinpoint the offending Workflow

Example fix

// before
templates:
  main: {...}
// after
templates:
  - name: main
    ...

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

if ! argo convert "$f" 2>err; then
  grep 'failed to parse Workflow' err && echo 'check the yaml path/type in the wrapped error'
fi

When it happens

Trigger: `argo convert` on a Workflow manifest with type mismatches against the legacy struct — e.g. `templates` as a mapping instead of a list, `entrypoint` as a non-string, sync/semaphore fields with list-vs-string confusion, or malformed container/script blocks.

Common situations: Very large or heavily templated workflows assembled by scripts where a field got emitted with the wrong type; workflows copied from other engines (Airflow/K8s Jobs) with foreign fields reshaped wrongly; YAML anchors producing sequences where scalars are expected.

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 CronWorkflow
• failed to parse TypeMeta
• failed to parse WorkflowTemplate
• [ ].name ' ' is not unique
• error converting

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

Appendix: source

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

	if err := yaml.Unmarshal(data, &typeMeta); err != nil {
		return fmt.Errorf("failed to parse TypeMeta: %w", err)
	}

	var converted any

	// Parse into legacy type and convert to current type
	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:

View on GitHub (pinned to 35bff19146)