What causes "error parsing template %q: %w" in kubernetes/kops?

Fix the template syntax in the named file (check for balanced {{ if }}/{{ range }} with {{ end }})

error parsing template %q: %w

Error message

error parsing template %q: %w

What it means

kOps renders cluster templates (e.g. addons, manifests) as Go text/template with a set of template functions. RenderTemplate wraps any template.Parse failure — syntax errors, unclosed actions, bad pipeline — with this message so the offending template name is identifiable.

Source

Thrown at upup/pkg/fi/cloudup/template_functions.go:128

// RenderTemplate parses and executes an addon template source against a func map
// derived from a per-call *TemplateFunctions bound to the given task graph.
// When tasks is nil, task-based functions return empty stubs so templates still
// render — used for Build-time image discovery before the task graph exists.
func (r *addonTemplateRenderer) RenderTemplate(name string, source []byte, tasks map[string]fi.CloudupTask) ([]byte, error) {
	tf := r.newTemplateFunctions(tasks)
	funcMap := template.FuncMap{}
	if err := tf.AddTo(funcMap, r.secretStore); err != nil {
		return nil, err
	}
	if tasks == nil {
		funcMap["Task"] = func(typeName, name string) (fi.CloudupTask, error) { return nil, nil }
		funcMap["HasTask"] = func(typeName, name string) bool { return false }
		funcMap["TasksByType"] = func(typeName string) ([]fi.CloudupTask, error) { return nil, nil }
	}

	t := template.New(name).Funcs(funcMap).Option("missingkey=zero")
	if _, err := t.Parse(string(source)); err != nil {
		return nil, fmt.Errorf("error parsing template %q: %w", name, err)
	}

	var buf bytes.Buffer
	if err := t.ExecuteTemplate(&buf, name, r.modelContext.Cluster.Spec); err != nil {
		return nil, fmt.Errorf("error executing template %q: %w", name, err)
	}
	return buf.Bytes(), nil
}

// CloudControllerConfigArgv returns the cloud controller argv without binding any task graph.
func (r *addonTemplateRenderer) CloudControllerConfigArgv() ([]string, error) {
	return r.newTemplateFunctions(nil).CloudControllerConfigArgv()
}

// AddTo defines the available functions we can use in our YAML models.
// If we are trying to get a new function implemented it MUST
// be defined here.
func (tf *TemplateFunctions) AddTo(dest template.FuncMap, secretStore fi.SecretStore) (err error) {

View on GitHub (pinned to 4c8573c808)

Solutions

Fix the template syntax in the named file (check for balanced {{ if }}/{{ range }} with {{ end }})
Render the template locally with a minimal Go text/template harness to see the raw parser error wrapped by %w
Diff the template against a stock kOps template of the same version to spot incompatible function usage

Example fix

// before
{{ range .Subnets }}
  name: {{ .Name }}
{{ range }}
// after
{{ range .Subnets }}
  name: {{ .Name }}
{{ end }}

Defensive patterns

Strategy: try-catch

Validate before calling

var buf bytes.Buffer
tmpl := template.New(name).Funcs(safeFuncMap)
if err := tmpl.Parse(source); err != nil {
	return fmt.Errorf("template %s has syntax errors: %w", name, err)
}

Try / catch

out, err := r.RenderTemplate(name, source)
if err != nil && strings.Contains(err.Error(), "error parsing template") {
	log.Fatalf("fix syntax in template %s: %v", name, err)
}

Prevention

Lint Go templates in CI (e.g. parse them with text/template as a test)
Balance every {{ if }}/{{ range }} with {{ end }} before committing
Pin template function usage to your kOps version's funcMap

When it happens

Trigger: Calling RenderTemplate with template source containing Go template syntax errors: `{{ end }}` without `{{ if }}`, unclosed `{{`, unknown constructs, or invalid usage of registered funcs.

Common situations: Custom addon manifests edited by hand; broken templated cluster spec files; upgrading kOps changes available template functions leaving invalid calls.

Related errors

AI-assisted analysis of kubernetes/kops@4c8573c808 (2026-09-05). Data as JSON: /api/errors/d0abee3d743a63a4. Report an issue: GitHub.