argoproj/argo-workflows · error

couldn't find cluster workflow template %q

Error message

couldn't find cluster workflow template %q

What it means

offlineClusterWorkflowTemplateGetter.Get is the in-memory stand-in for the ClusterWorkflowTemplate service. If a cluster-scoped templateRef cannot be found among the loaded manifests, it returns this error naming the missing cluster template.

Source

Thrown at pkg/apiclient/offline-client.go:163

}

func (w offlineWorkflowTemplateNamespacedGetter) Get(_ context.Context, name string) (*wfv1.WorkflowTemplate, error) {
	if v, ok := w.workflowTemplates[name]; ok {
		return v, nil
	}
	return nil, fmt.Errorf("couldn't find workflow template %q in namespace %q", name, w.namespace)
}

type offlineClusterWorkflowTemplateGetter struct {
	clusterWorkflowTemplates map[string]*wfv1.ClusterWorkflowTemplate
}

func (o offlineClusterWorkflowTemplateGetter) Get(_ context.Context, name string) (*wfv1.ClusterWorkflowTemplate, error) {
	if v, ok := o.clusterWorkflowTemplates[name]; ok {
		return v, nil
	}

	return nil, fmt.Errorf("couldn't find cluster workflow template %q", name)
}

View on GitHub (pinned to 35bff19146)

Solutions

1. Include the file defining the referenced ClusterWorkflowTemplate in the linted paths.
2. Correct the templateRef.name to match the defined cluster template.
3. List loaded cluster templates (or grep manifests for kind: ClusterWorkflowTemplate) to confirm the name exists.

Example fix

// before
argo lint ./workflow.yaml
// after
argo lint ./cluster-templates/ ./workflow.yaml

// collect cluster template names from manifests:
clusterTmpls := map[string]bool{} // from kind: ClusterWorkflowTemplate docs
// for each templateRef with clusterScope: if !clusterTmpls[ref.Name] { fail early }

err := lint(ctx, paths)
if err != nil && strings.Contains(err.Error(), "couldn't find cluster workflow template") {
    // extract name, include its defining file in the offline client paths
    return fmt.Errorf("missing ClusterWorkflowTemplate in lint input: %w", err)
}

When it happens

Trigger: During offline lint/templateresolution, a templateRef with clusterScope: true references a ClusterWorkflowTemplate name that was not included in the paths given to newOfflineClient.

Common situations: Linting workflow files without including the ClusterWorkflowTemplate manifest they depend on; typo in templateRef.name; forgetting that cluster templates live outside any namespace and were not part of the walked directory.

Related errors

• couldn't find workflow template %q in namespace %q
• not supported when you are in offline mode
• failed to parse YAML from file %s: %w
• duplicate ClusterWorkflowTemplate found: %q
• duplicate WorkflowTemplate found: %q

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