argoproj/argo-workflows · error

failed to parse unknown kind %s: %w

Error message

failed to parse unknown kind %s: %w

What it means

During `argo convert`, a document with a kind not among the known legacy kinds (Workflow, CronWorkflow, WorkflowTemplate, ClusterWorkflowTemplate) falls through to the default branch and is re-parsed as a generic map for passthrough. This error means even that generic `map[string]any` unmarshal failed, i.e. the document is not structurally valid YAML/JSON at all, independent of kind.

Source

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

		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
	var err error

	// Output JSON if format is "json", or if input was JSON and format is not explicitly "yaml"
	// This preserves input format by default while allowing explicit format override
	outputJSON := format == "json" || (preferJSON && format != "yaml")

	if outputJSON {
		outBytes, err = json.Marshal(obj)
		if err != nil {

View on GitHub (pinned to 35bff19146)

Solutions

1. Fix the YAML syntax error reported by the wrapped error (check indentation, tabs, and that the top level is a mapping).
2. Run `argo convert` with `--format json`/lint tooling to isolate the malformed document in a multi-doc file.
3. If the kind is a typo of a known kind, correct the `kind:` field so the proper legacy struct handles it.
4. Verify the input file is not empty, truncated, or binary.

Example fix

# before (top-level list, not a mapping)
- name: main
  template: whalesay
# after
apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  name: main-wf
spec:
  templates:
    - name: main
      template: whalesay

// pre-parse as a mapping and check kind before converting
var doc map[string]any
if err := yaml.Unmarshal(data, &doc); err != nil {
  return fmt.Errorf("not valid YAML mapping: %w", err)
}
if _, ok := doc["kind"]; !ok { return errors.New("missing kind") }

if err := convertDocument(data, out, isJSON); err != nil {
  if strings.Contains(err.Error(), "failed to parse unknown kind") {
    log.Printf("skipping unparseable non-argo document")
    return nil
  }
  return err
}

When it happens

Trigger: `argo convert` given a document whose kind is unrecognized (or empty) AND whose content is not parseable into a YAML object mapping: invalid YAML syntax, tabs in indentation, top-level scalars or lists instead of a mapping, duplicate keys rejected by the parser.

Common situations: Passing non-YAML files (binaries, plain text, empty files) to convert; a multi-document file where a later document is malformed; files with kind typos like "WorkflowTemplates" that skip the known-kind branches and then hit deeper syntax errors.

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 ClusterWorkflowTemplate: %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/c154795c43522167. Report an issue: GitHub.