argoproj/argo-workflows · error

failed to parse Workflow: %w

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.

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)

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 TypeMeta: %w
• failed to parse CronWorkflow: %w
• failed to parse WorkflowTemplate: %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/7df4bdaec90d7b89. Report an issue: GitHub.