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

The `images.Filter` function applies one or more image filters to an image resource. The image resource must be the last argument and at least one filter must precede it. The check at images.go:99–100 requires `len(args) >= 2` (at least one filter + the image).

Solutions

1. Ensure the last argument is the image resource and at least one filter precedes it: `{{ (images.Filter $filter1 $filter2 $image) }}`.
2. Check argument order — image comes last, not first.
3. Verify the image variable is a valid `images.ImageResource`.

Example fix

// before
{{ (images.Filter $image $filter) }}
// after
{{ (images.Filter $filter $image) }}

// Ensure image is last and at least one filter precedes it
{{ if and (ge (len $args) 2) (isImageResource (index $args (sub (len $args) 1))) }}
  {{ (images.Filter $args...) }}
{{ end }}

func validFilterArgs(args []any) bool {
    if len(args) < 2 { return false }
    _, ok := args[len(args)-1].(images.ImageResource)
    return ok
}

When it happens

Trigger: Calling `{{ (images.Filter $filter) }}` (only a filter, no image), `{{ (images.Filter $img) }}` (only an image, no filter), or `{{ images.Filter }}` (no args).

Common situations: A developer places the image first and the filter second (reversed order), or passes only the filter expecting it to apply to the current page's image. The last argument must be the image.

Related errors

• requires 1 or 2 arguments
• can't evaluate the array by no match argument or more than…
• cannot encode an empty string
• complement needs at least two arguments
• config needs a filename

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

Appendix: 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 52c9bd7908)