{"id":"5dc5732238d72a9e","repo":"gohugoio/hugo","slug":"failed-to-render-shortcode-q-w","errorCode":null,"errorMessage":"failed to render shortcode %q: %w","messagePattern":"failed to render shortcode %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"hugolib/shortcode.go","lineNumber":332,"sourceCode":"}\n\nconst (\n\tinnerNewlineRegexp = \"\\n\"\n\tinnerCleanupRegexp = `\\A<p>(.*)</p>\\n\\z`\n\tinnerCleanupExpand = \"$1\"\n)\n\nfunc prepareShortcode(\n\tlevel int,\n\tsc *shortcode,\n\tparent *ShortcodeWithPage,\n\tpo *pageOutput,\n\tisRenderString bool,\n) (shortcodeRenderer, error) {\n\tp := po.p\n\ttoParseErr := func(err error) error {\n\t\tsource := p.m.content.mustSource()\n\t\treturn p.parseError(fmt.Errorf(\"failed to render shortcode %q: %w\", sc.name, err), source, sc.pos)\n\t}\n\n\t// Allow the caller to delay the rendering of the shortcode if needed.\n\tvar fn shortcodeRenderFunc = func(ctx context.Context) ([]byte, bool, error) {\n\t\tif p.m.pageConfigSource.ContentMediaType.IsMarkdown() && sc.doMarkup {\n\t\t\t// Signal downwards that the content rendered will be\n\t\t\t// parsed and rendered by Goldmark.\n\t\t\tctx = tpl.Context.IsInGoldmark.Set(ctx, true)\n\t\t}\n\t\tr, err := doRenderShortcode(ctx, level, po.p.s.TemplateStore, sc, parent, po, isRenderString)\n\t\tif err != nil {\n\t\t\treturn nil, false, toParseErr(err)\n\t\t}\n\n\t\tb, hasVariants, err := r.renderShortcode(ctx)\n\t\tif err != nil {\n\t\t\treturn nil, false, toParseErr(err)\n\t\t}","sourceCodeStart":314,"sourceCodeEnd":350,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/hugolib/shortcode.go#L314-L350","documentation":"This wraps any failure that occurs while rendering a specific shortcode on a page — template resolution, template execution, or rendering of its output. Hugo attaches the shortcode name and, via p.parseError with the shortcode's source position, the file and line so the user can locate the failing shortcode call in their content.","triggerScenarios":"prepareShortcode's render function failing in doRenderShortcode or renderShortcode: the shortcode template panics/errors during execution (nil pointer on .Params, failed function call, type error), a nested shortcode fails, or template lookup/parse of an inline shortcode fails.","commonSituations":"Shortcode templates referencing missing params (.Get on absent keys used unsafely), errors in partials called from the shortcode, resources.Get failures inside the template, upgrades where template functions changed behavior, errors inside {{% %}} markdown-rendered shortcodes.","solutions":["Read the wrapped error — it identifies the actual template failure; fix that expression in layouts/_shortcodes/<name>.html.","Guard optional params in the shortcode template (e.g. {{ with .Get \"param\" }}...{{ end }}).","Reproduce with 'hugo --panicOnWarning=false -v' or 'hugo server' to get the file:line position reported and inspect that shortcode invocation in the content file."],"exampleFix":"{{/* before: layouts/_shortcodes/img.html */}}\n<img src=\"{{ (resources.Get (.Get \"src\")).RelPermalink }}\">\n\n{{/* after */}}\n{{ with resources.Get (.Get \"src\") }}\n<img src=\"{{ .RelPermalink }}\">\n{{ else }}\n{{ errorf \"img shortcode: resource %q not found\" (.Get \"src\") }}\n{{ end }}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"err := h.Build(BuildCfg{})\nif err != nil {\n    var fe herrors.FileError\n    if errors.As(err, &fe) {\n        // fe.Position() gives file:line of the failing shortcode call\n    }\n    return err\n}","preventionTips":["Test shortcode templates in isolation with a minimal page before wide use","Guard nil params inside shortcode templates: {{ with .Get 0 }}...{{ end }}","Use errors.As with herrors.FileError to surface the exact content file and position","Fail the build in CI on any shortcode render error rather than ignoring it"],"tags":["hugo","shortcode","template","rendering"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}