gohugoio/hugo · error

template: no template %q associated with template %q

Error message

template: no template %q associated with template %q

What it means

Returned by text/template ExecuteTemplate when t.Lookup(name) is nil, i.e. no template with that name is associated with t. Unlike html/template, text/template ExecuteTemplate performs the lookup directly and errors if the name is unknown. The first %q is the missing name, the second %q is the parent template's own name.

Source

Thrown at tpl/internal/go_templates/texttemplate/exec.go:191

		case ExecError:
			*errp = err // Keep the wrapper.
		default:
			panic(e)
		}
	}
}

// ExecuteTemplate applies the template associated with t that has the given name
// to the specified data object and writes the output to wr.
// If an error occurs executing the template or writing its output,
// execution stops, but partial results may already have been written to
// the output writer.
// A template may be executed safely in parallel, although if parallel
// executions share a Writer the output may be interleaved.
func (t *Template) ExecuteTemplate(wr io.Writer, name string, data any) error {
	tmpl := t.Lookup(name)
	if tmpl == nil {
		return fmt.Errorf("template: no template %q associated with template %q", name, t.name)
	}
	return tmpl.Execute(wr, data)
}

// Execute applies a parsed template to the specified data object,
// and writes the output to wr.
// If an error occurs executing the template or writing its output,
// execution stops, but partial results may already have been written to
// the output writer.
// A template may be executed safely in parallel, although if parallel
// executions share a Writer the output may be interleaved.
//
// If data is a [reflect.Value], the template applies to the concrete
// value that the reflect.Value holds, as in [fmt.Print].
func (t *Template) Execute(wr io.Writer, data any) error {
	return t.execute(wr, data)
}

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Confirm name exactly matches a {{define}} name or a parsed file's base name in t's association set.
2. Call t.Lookup(name) before ExecuteTemplate and report available names if nil.
3. Ensure all sub-templates are parsed into the same set (shared via t.Parse of definitions or t.New).
4. Use t.DefinedTemplates() in the error message to list what is actually available.

Example fix

// before
err := t.ExecuteTemplate(w, "layout", data) // error: not associated

// after
if t.Lookup("layout") == nil {
    return fmt.Errorf("layout not found; defined:%s", t.DefinedTemplates())
}
err := t.ExecuteTemplate(w, "layout", data)

func execText(t *template.Template, name string, w io.Writer, data any) error {
    if t.Lookup(name) == nil {
        return fmt.Errorf("no template %q; defined:%s", name, t.DefinedTemplates())
    }
    return t.ExecuteTemplate(w, name, data)
}

if err := t.ExecuteTemplate(w, name, data); err != nil {
    if strings.Contains(err.Error(), "no template") {
        return t.ExecuteTemplate(w, defaultName, data)
    }
    return err
}

When it happens

Trigger: Calling (*texttemplate.Template).ExecuteTemplate(w, name, data) where name is not present among the templates associated with t (never defined, typo, or defined in a separate unassociated set).

Common situations: Typo in the template name; templates parsed into separate New() sets instead of one association; referencing a sub-template that a missing {{define}} was supposed to create; refactor that renamed a template without updating callers.

Related errors

• html/template: %q is undefined
• html/template: %q is an incomplete template
• invalid function signature for %s: second return value shoul
• function %s has %d return values; should be 1 or 2
• value is nil; should be of type %s

AI-assisted analysis of gohugoio/hugo@52c9bd7908 (2026-08-09). Data as JSON: /api/errors/cb2e7086be8d31b0. Report an issue: GitHub.