What causes "failed to get a template" in argoproj/argo-workflows?

Inspect the offending holder in the workflow spec and set a valid `template:` name, `templateRef:`, or inline `template:` block.

argoproj/argo-workflows · error

500

500

Error message

failed to get a template

What it means

GetTemplate walks a template holder's three reference mechanisms in priority order: inline template (GetTemplate), templateRef (GetTemplateFromRef), then templateName (GetTemplateByName). If none of the three is populated — the holder has no template, no templateRef, and an empty templateName — the code falls through and raises a coded internal error (errors.CodeInternal, HTTP 500). Unlike the 404s, this indicates a malformed spec rather than missing cluster state.

Source

Thrown at workflow/templateresolution/context.go:164

	}

	podMetadata := wftmpl.GetPodMetadata()
	tplCtx.addPodMetadata(podMetadata, template)

	return template.DeepCopy(), nil
}

// GetTemplate returns a template found by template name or template ref.
func (tplCtx *TemplateContext) GetTemplate(ctx context.Context, h wfv1.TemplateReferenceHolder) (*wfv1.Template, error) {
	tplCtx.log.Debug(ctx, "Getting the template")
	if x := h.GetTemplate(); x != nil {
		return x, nil
	} else if x := h.GetTemplateRef(); x != nil {
		return tplCtx.GetTemplateFromRef(ctx, x)
	} else if x := h.GetTemplateName(); x != "" {
		return tplCtx.GetTemplateByName(ctx, x)
	}
	return nil, errors.Errorf(errors.CodeInternal, "failed to get a template")
}

// GetCurrentTemplateBase returns the current template base of the context.
func (tplCtx *TemplateContext) GetCurrentTemplateBase() wfv1.TemplateHolder {
	return tplCtx.tmplBase
}

func (tplCtx *TemplateContext) GetTemplateScope() string {
	return string(tplCtx.tmplBase.GetResourceScope()) + "/" + tplCtx.tmplBase.GetName()
}

// ResolveTemplate digs into referenes and returns a merged template.
// This method is the public start point of template resolution.
func (tplCtx *TemplateContext) ResolveTemplate(c context.Context, tmplHolder wfv1.TemplateReferenceHolder) (*TemplateContext, *wfv1.Template, bool, error) {
	return tplCtx.resolveTemplateImpl(c, tmplHolder)
}

// resolveTemplateImpl digs into references and returns a merged template.

View on GitHub (pinned to 35bff19146)

Solutions

Inspect the offending holder in the workflow spec and set a valid `template:` name, `templateRef:`, or inline `template:` block.
Run `argo lint` on the workflow/WorkflowTemplate to catch templates missing a reference before submission.
If a custom tool builds the spec, fix it to always populate one of the three template reference fields.

Example fix

# before
- name: step-one
  args: ["--flag"]      # no template reference at all
# after
- name: step-one
  template: run-job     # or templateRef / inline template
  args: ["--flag"]

Defensive patterns

Strategy: validation

Validate before calling

# shell: every step/dag task must reference a template somehow
yq '.spec.templates[] | select((.template == null) and (.templateRef == null) and ((.templateName // "") == "")) | .name' workflow.yaml
# any output = spec will hit the internal error

Try / catch

// Go: treat CodeInternal here as a spec bug, not a runtime condition
tmpl, err := tplCtx.GetTemplate(ctx, holder)
if err != nil {
	if argoErr, ok := err.(errors.ArgoError); ok && argoErr.Code() == errors.CodeInternal {
		return fmt.Errorf("holder %v declares no template/templateRef/templateName — fix the spec", holder)
	}
	return err
}

Prevention

Run `argo lint` on every generated or hand-written workflow before submission.
When generating workflows programmatically, assert each node/step sets exactly one of template, templateRef, or templateName.
Avoid custom mutation that strips template fields from workflow specs.

When it happens

Trigger: Calling GetTemplate (via ResolveTemplate during validation or controller execution) on a TemplateReferenceHolder (e.g. a workflow step/node) whose template, templateRef, and templateName fields are all unset/empty — typically only possible with a programmatically constructed or corrupted object.

Common situations: Hand-crafted workflow YAML where a step declares neither `template:` nor `templateRef:`; a controller/tool that builds Workflow nodes without setting any template reference; bugs in custom automation that mutates workflow specs (stripping template fields).

Related errors

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