gohugoio/hugo · error

must provide an image and one or more filters

Error message

must provide an image and one or more filters

What it means

`images.Filter` applies one or more image filters to an image resource, which by its calling convention (pipe-friendly) is the last argument. With fewer than two arguments there is either no filter or no image, so Hugo rejects the call before attempting the type assertion on the last argument.

Source

Thrown at tpl/images/images.go:100

	return ns.cache.GetOrCreate(filename, func() (image.Config, error) {
		f, err := ns.readFileFs.Open(filename)
		if err != nil {
			return image.Config{}, err
		}
		defer f.Close()

		ext := filepath.Ext(filename)
		format, _ := images.ImageFormatFromExt(ext)

		config, _, err := ns.deps.ResourceSpec.Imaging.Codec.DecodeConfig(format, f)
		return config, err
	})
}

// Filter applies the given filters to the image given as the last element in args.
func (ns *Namespace) Filter(args ...any) (images.ImageResource, error) {
	if len(args) < 2 {
		return nil, errors.New("must provide an image and one or more filters")
	}

	img := args[len(args)-1].(images.ImageResource)
	filtersv := args[:len(args)-1]

	return img.Filter(filtersv...)
}

var qrErrorCorrectionLevels = map[string]qr.Level{
	"low":      qr.L,
	"medium":   qr.M,
	"quartile": qr.Q,
	"high":     qr.H,
}

// QR encodes the given text into a QR code using the specified options,
// returning an image resource.
func (ns *Namespace) QR(args ...any) (images.ImageResource, error) {

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Pass at least one filter plus the image: `{{ $img = $img.Filter (images.GaussianBlur 6) }}` or `{{ images.Filter (images.Grayscale) $img }}`.
2. If filters are built dynamically, skip the call when the list is empty: `{{ with $filters }}{{ $img = images.Filter . $img }}{{ end }}` (spread as needed).
3. Check the pipe order — the image must be the last argument (`{{ $img | images.Filter $f1 $f2 }}`).

Example fix

<!-- before -->
{{ $img = images.Filter $img }}
<!-- after -->
{{ $img = images.Filter (images.Grayscale) $img }}

{{ $img := resources.Get "photo.jpg" }}
{{ $filters := slice (images.GaussianBlur 6) }}
{{ if and $img (gt (len $filters) 0) }}
  {{ $img = $img.Filter $filters }}
{{ end }}

When it happens

Trigger: Calling `{{ images.Filter $img }}` with no filters, `{{ images.Filter $filter }}` without piping an image, or `{{ $img | images.Filter }}` where the filter list is empty/nil so only one argument reaches the function.

Common situations: Building the filter list dynamically (e.g. from `slice`) and it ends up empty; forgetting that the image must be piped in or passed last; copying `.Filter` method examples into the `images.Filter` function form incorrectly.

Related errors

• need at least 2 arguments to append
• must provide a Resource and optionally an options map
• operator argument must be string type
• can't evaluate the array by no match argument or more than o
• invalid arguments supplied to `time`

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