argoproj/argo-workflows · error

failed to parse ClusterWorkflowTemplate: %w

Error message

failed to parse ClusterWorkflowTemplate: %w

What it means

During `argo convert`, a YAML document whose kind is ClusterWorkflowTemplate failed to unmarshal into the legacy ClusterWorkflowTemplate struct. The command parses legacy-format manifests into typed structs before migrating them to the current schema; yaml.Unmarshal returned an error for this document. The wrapped inner error describes the exact field/type mismatch or malformed YAML.

Source

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

	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
	}

	return outputObject(converted, outputFormat, isJSON)
}

func outputObject(obj any, format string, preferJSON bool) error {
	var outBytes []byte

View on GitHub (pinned to 35bff19146)

Solutions

1. Read the wrapped error to find the exact field/line, and fix the YAML syntax or field type in the source manifest.
2. Validate the document with `argo lint` or a YAML parser before converting.
3. Confirm the manifest is really a ClusterWorkflowTemplate and not a similarly-named kind (kind string must match exactly).
4. If the file is already in current schema, convert the documents that are actually legacy, or rely on the unknown-kind passthrough by adjusting the kind.

Example fix

// before (manifest with wrong field type)
spec:
  templates:
    - name: main
      retryStrategy: "not-a-struct"
// after
spec:
  templates:
    - name: main
      retryStrategy:
        limit: 3

// lint the manifest before converting
if err := yaml.Unmarshal(data, &struct{
  APIVersion string `yaml:"apiVersion"`
  Kind string `yaml:"kind"`
  Spec  map[string]any `yaml:"spec"`
}{}); err != nil {
  return fmt.Errorf("invalid ClusterWorkflowTemplate YAML: %w", err)
}

// in Go, check the wrapped error to locate the failing field
if err := convertDocument(data, out, isJSON); err != nil {
  var tErr *yaml.TypeError
  if errors.As(err, &tErr) {
    for _, te := range tErr.Errors { log.Printf("yaml type error: %s", te) }
  }
  return err
}

When it happens

Trigger: Running `argo convert` on a file containing `kind: ClusterWorkflowTemplate` whose YAML does not match the LegacyClusterWorkflowTemplate struct: malformed YAML syntax, wrong types for fields (e.g. string where an int is expected), or invalid values for typed fields (enums, durations, quantities).

Common situations: Hand-edited manifests with indentation or type mistakes; manifests exported from other tools with incompatible field types; partially migrated multi-document files mixing old and new schema; YAML containing duplicate keys or unparseable blocks.

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 unknown kind %s: %w
• no workflow found in given files
• failed to parse TypeMeta: %w
• failed to parse CronWorkflow: %w
• failed to parse Workflow: %w

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