gohugoio/hugo · error

failed to process shortcode: %w

Error message

failed to process shortcode: %w

What it means

Raised in renderShortcodeWithPage (hugolib/shortcode.go:778) when executing a shortcode template via the template store fails. Hugo wraps the underlying template execution error so the user sees which stage failed; the real cause is inside the wrapped error — a template syntax/runtime error, a nil or missing value, or a failing function call inside the shortcode template.

Source

Thrown at hugolib/shortcode.go:778

		}

		// This and other cool slice tricks: https://github.com/golang/go/wiki/SliceTricks
		source = append(source[:j], append(newVal, source[end:]...)...)
		start = j
		k = bytes.Index(source[start:], pre)

	}

	return source, nil
}

func renderShortcodeWithPage(ctx context.Context, h *tplimpl.TemplateStore, tmpl *tplimpl.TemplInfo, data *ShortcodeWithPage) (string, error) {
	buffer := bp.GetBuffer()
	defer bp.PutBuffer(buffer)

	err := h.ExecuteWithContext(ctx, tmpl, buffer, data)
	if err != nil {
		return "", fmt.Errorf("failed to process shortcode: %w", err)
	}
	return buffer.String(), nil
}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Read the wrapped error after the colon — it names the template file, line, and the actual failure.
2. Fix the shortcode template: guard optional params (e.g. {{ with .Get "param" }}) and nil resources before use.
3. Check the calling page's shortcode invocation for missing/misspelled parameters.
4. If it appeared after upgrading Hugo, check the release notes for removed template methods used by the shortcode.

Example fix

// before (layouts/_shortcodes/img.html)
{{ $img := resources.Get (.Get "src") }}
<img src="{{ $img.RelPermalink }}">
// after
{{ with resources.Get (.Get "src") }}
<img src="{{ .RelPermalink }}">
{{ else }}
{{ errorf "img shortcode: resource %q not found in %s" (.Get "src") .Page.Path }}
{{ end }}

err := hugolib.Build(...)
if err != nil {
    // wrapped chain: "failed to process shortcode: ..." carries position info
    var fe herrors.FileError
    if errors.As(err, &fe) {
        log.Printf("shortcode error at %s: %v", fe.Position(), fe)
    }
    return err
}

When it happens

Trigger: Any page containing {{< myshortcode >}} or {{% myshortcode %}} whose template (layouts/_shortcodes/myshortcode.html or an embedded shortcode) errors during ExecuteWithContext — e.g. calling a method on nil, .Get with a missing param used unsafely, errorf/resources.GetRemote failures, or a Go template runtime error.

Common situations: Custom shortcodes broken after a Hugo upgrade (deprecated methods removed), shortcodes assuming a named parameter that a page omits, resources/images referenced by the shortcode not existing, or partials called from the shortcode failing. Often surfaces only for the one page passing bad arguments.

Related errors

• failed to render shortcode %q: %w
• %s: shortcode %q does not evaluate .Inner or .InnerDeindent,
• quality ranges from 1 to 100 inclusive
• invalid image dimensions
• must provide Width and Height

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