{"id":"10ee2f8a81b9b049","repo":"gohugoio/hugo","slug":"s-template-for-shortcode-q-not-found","errorCode":null,"errorMessage":"%s: template for shortcode %q not found","messagePattern":"(.+?): template for shortcode %q not found","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"hugolib/shortcode.go","lineNumber":671,"sourceCode":"\t\t\tif next.IsRightShortcodeDelim() {\n\t\t\t\t// self-closing\n\t\t\t\tpt.Consume(1)\n\t\t\t} else {\n\t\t\t\tsc.isClosing = true\n\t\t\t\tpt.Consume(2)\n\t\t\t}\n\t\t\treturn sc, nil\n\t\tcase currItem.IsText():\n\t\t\tsc.inner = append(sc.inner, currItem.ValStr(source))\n\t\tcase currItem.IsShortcodeName():\n\n\t\t\tsc.name = currItem.ValStr(source)\n\n\t\t\t// Used to check if the template expects inner content,\n\t\t\t// so just pick one arbitrarily with the same name.\n\t\t\ttempl := s.firstTemplateStore.LookupShortcodeByName(sc.name)\n\t\t\tif templ == nil {\n\t\t\t\treturn nil, fmt.Errorf(\"%s: template for shortcode %q not found\", errorPrefix, sc.name)\n\t\t\t}\n\t\t\tsc.templ = templ\n\t\tcase currItem.IsInlineShortcodeName():\n\t\t\tsc.name = currItem.ValStr(source)\n\t\t\tsc.isInline = true\n\t\tcase currItem.IsShortcodeParam():\n\t\t\tif !pt.IsValueNext() {\n\t\t\t\tcontinue\n\t\t\t} else if pt.Peek().IsShortcodeParamVal() {\n\t\t\t\t// named params\n\t\t\t\tif sc.params == nil {\n\t\t\t\t\tparams := make(map[string]any)\n\t\t\t\t\tparams[currItem.ValStr(source)] = pt.Next().ValTyped(source)\n\t\t\t\t\tsc.params = params\n\t\t\t\t} else {\n\t\t\t\t\tif params, ok := sc.params.(map[string]any); ok {\n\t\t\t\t\t\tparams[currItem.ValStr(source)] = pt.Next().ValTyped(source)\n\t\t\t\t\t} else {","sourceCodeStart":653,"sourceCodeEnd":689,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/hugolib/shortcode.go#L653-L689","documentation":"During shortcode extraction, as soon as the parser reads a shortcode's name it looks up any template with that name (LookupShortcodeByName) to learn whether it expects inner content. If no shortcode template with that name exists anywhere in the project, themes, or Hugo's embedded templates, extraction fails with this error — the shortcode simply isn't defined.","triggerScenarios":"Content calling {{< name >}} / {{% name %}} where no layouts/_shortcodes/name.* (or legacy layouts/shortcodes/name.*) template exists in the project, any mounted module/theme, or Hugo's built-ins.","commonSituations":"Typos in the shortcode name; theme not installed or module mount missing so the theme's shortcodes are absent; migrating content between sites that used different custom shortcodes; using a shortcode removed in a Hugo upgrade; unescaped example shortcode syntax in docs content.","solutions":["Check the name for typos and confirm a matching template exists at layouts/_shortcodes/<name>.html (or in the theme).","Ensure the theme/module providing the shortcode is actually installed and enabled ('hugo mod graph', check theme in config).","Create the missing shortcode template, or remove/escape the call ({{</* name */>}}) if it's documentation of syntax."],"exampleFix":"<!-- before: content uses {{< alert >}} but no template exists -->\n\n{{/* after: create layouts/_shortcodes/alert.html */}}\n<div class=\"alert\">{{ .Inner }}</div>","handlingStrategy":"validation","validationCode":"// Verify the shortcode template exists in the lookup path\n// test -f layouts/_shortcodes/<name>.html || test -f themes/<theme>/layouts/_shortcodes/<name>.html","typeGuard":null,"tryCatchPattern":"if err := h.Build(cfg); err != nil {\n    if strings.Contains(err.Error(), \"template for shortcode\") {\n        // list available shortcodes to diagnose typos\n    }\n    return err\n}","preventionTips":["Match the shortcode call name exactly to the template filename (case-sensitive on Linux)","Place custom shortcodes in layouts/_shortcodes/ (current spec), not stale paths","Remember embedded shortcodes (figure, highlight, ref) exist only if not disabled; check theme provides the rest","Escape literal shortcode syntax in docs with {{</* name */>}}"],"tags":["hugo","shortcode","template-lookup","content"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}