gohugoio/hugo · error

no compatible template found for shortcode %q in %s

Error message

no compatible template found for shortcode %q in %s

What it means

Thrown by TemplateStore when a shortcode referenced in content has candidate templates but none are compatible with the requested category/descriptor after scoring (tpl/tplimpl/templatestore.go:686-693). A common sub-cause is using an HTML shortcode delimiter for a plain-text-only template, which appends the hint about {{% delimiters.

Source

Thrown at tpl/tplimpl/templatestore.go:693

			weight := s.dh.compareDescriptors(q.Category, q.Desc, k, q.Sites, vv.matrix)
			weight.distance = distance
			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 {

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Check the shortcode name spelling in the content file matches a file under layouts/shortcodes/.
2. If the template is plain-text, invoke with the {{% %}} delimiter instead of {{< >}}.
3. Add the missing shortcode template or remove the call from content.
4. If using overlays/multi-site, verify the template is present for the relevant site/language and output format.

Example fix

// before
{{< myshortcode >}}
// after (for a plain-text shortcode)
{{% myshortcode %}}

{{/* Ensure shortcode name matches a layouts/shortcodes/<name>.html file */}}

When it happens

Trigger: Content uses {{< mycode >}} but only a plain-text shortcode template (layouts/shortcodes/mycode.html written for {{% }}) exists; or category/output-format/overlay/site filters exclude every candidate.

Common situations: Theme update that renamed or removed a shortcode; site overlay partially overriding a shortcode; mismatched base vs language template; wrong delimiter for the template type; plain-text shortcode used in HTML context without {{% }}.

Related errors

• failed to process shortcode: %w
• resources.PostProcess cannot be used in a deferred template
• %s: invalid state: invalid param type %T for shortcode %q, e
• %s: invalid state: invalid param type %T for shortcode %q, e
• %s: shortcode %q must be closed or self-closed

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