gohugoio/hugo · error

no template found for shortcode %q

Error message

no template found for shortcode %q

What it means

When rendering `{{< name >}}` / `{{% name %}}` in content, Hugo's TemplateStore looks up a shortcode template by name across project, theme, and embedded templates. If no candidate template exists at all for that name, this error is returned (a sibling error, 'no compatible template found', fires when candidates exist but none match the output format/plain-text mode).

Source

Thrown at tpl/tplimpl/templatestore.go:695

			isBetter := best.isBetter(weight, vv)
			if isBetter {
				best.updateValues(weight, k2, k, vv)
			}
		}

		return false, nil
	})

	if best.w.w1 <= 0 {
		var err error
		if s := best.candidatesAsStringSlice(); s != nil {
			msg := fmt.Sprintf("no compatible template found for shortcode %q in %s", q.Name, s)
			if !q.Desc.IsPlainText {
				msg += "; note that to use plain text template shortcodes in HTML you need to use the shortcode {{% delimiter"
			}
			err = errors.New(msg)
		} else {
			err = fmt.Errorf("no template found for shortcode %q", q.Name)
		}
		return nil, err
	}

	return best.templ, nil
}

// PrintDebug is for testing/debugging only.
func (s *TemplateStore) PrintDebug(prefix string, category Category, w io.Writer) {
	if w == nil {
		w = os.Stdout
	}

	printOne := func(key string, vv *TemplInfo) {
		level := strings.Count(key, "/")
		if category != vv.category {
			return
		}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Check the spelling of the shortcode name in the content file against the filenames in layouts/_shortcodes/ (or the theme's).
2. Ensure the theme/module supplying the shortcode is actually installed and mounted (run `hugo mod graph` or verify the submodule is checked out).
3. Create the missing template, e.g. layouts/_shortcodes/<name>.html.
4. If the shortcode should output plain text (e.g. in RSS/plain formats), provide the matching variant such as <name>.txt.

Example fix

<!-- content: {{< youtube-embed id >}} fails -->
<!-- fix: create layouts/_shortcodes/youtube-embed.html -->
<div class="video">{{ .Get 0 }}</div>

# verify the shortcode file exists before using it in content
ls layouts/_shortcodes/myshortcode.html

When it happens

Trigger: Content using a shortcode `{{< foo >}}` when no `layouts/_shortcodes/foo.html` (or legacy `layouts/shortcodes/foo.html`) exists in the project, any mounted module, or the active theme, and it is not one of Hugo's embedded shortcodes.

Common situations: Typo in the shortcode name; theme not installed or module not mounted (missing `git submodule update` or `hugo mod get`); content copied from a site whose theme provided the shortcode; shortcode file placed in the wrong directory or with wrong extension for the output format.

Related errors

• error building site: %w
• failed to load modules: %w
• failed to create config from modules config: %w
• failed to detect format from content
• failed to detect target data serialization format

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/0d9267e59aed9de8.json. Report an issue: GitHub ↗.