gohugoio/hugo · error

the padding filter requires between 1 and 5 arguments

Error message

the padding filter requires between 1 and 5 arguments

What it means

Thrown by images.Padding when the variadic argument count is outside 1..5 (filters.go:149-151). Padding accepts 1-4 pixel values plus an optional trailing canvas color, so zero or more than five arguments are rejected up front.

Source

Thrown at resources/images/filters.go:150

			}
		}
	}

	return filter{
		Options: newFilterOpts(text, opt),
		Filter:  tf,
	}
}

// Padding creates a filter that resizes the image canvas without resizing the
// image. The last argument is the canvas color, expressed as an RGB or RGBA
// hexadecimal color. The default value is `ffffffff` (opaque white). The
// preceding arguments are the padding values, in pixels, using the CSS
// shorthand property syntax. Negative padding values will crop the image. The
// signature is images.Padding V1 [V2] [V3] [V4] [COLOR].
func (*Filters) Padding(args ...any) gift.Filter {
	if len(args) < 1 || len(args) > 5 {
		panic("the padding filter requires between 1 and 5 arguments")
	}

	var top, right, bottom, left int
	var ccolor color.Color = color.White // canvas color

	_args := args // preserve original args for most stable hash

	if vcs, ok, err := toColorGo(args[len(args)-1]); ok || err != nil {
		if err != nil {
			panic("invalid canvas color: specify RGB or RGBA using hex notation")
		}
		ccolor = vcs
		args = args[:len(args)-1]
		if len(args) == 0 {
			panic("not enough arguments: provide one or more padding values using the CSS shorthand property syntax")
		}
	}

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Provide between 1 and 5 arguments following the signature Padding V1 [V2] [V3] [V4] [COLOR].
2. If the color is omitted, ensure 1-4 pixel values are present.
3. Guard dynamic arg lists so they never collapse to zero or exceed five.

Example fix

// before
{{ $filters = $filters | append (images.Padding) }}
// after
{{ $filters = $filters | append (images.Padding 20) }}

{{ $args := slice }}
{{ range $v := .paddings }}{{ $args = $args | append $v }}{{ end }}
{{ if lt (len $args) 1 }}{{ errorf "Padding needs 1-5 args" }}{{ end }}
{{ if gt (len $args) 5 }}{{ errorf "Padding needs 1-5 args" }}{{ end }}

When it happens

Trigger: Calling images.Padding with no arguments, or with six or more arguments. Also triggered by accidentally passing a slice that expands into too many values.

Common situations: Template logic conditionally builds the arg list and ends up empty; developer misunderstands the signature as Padding(color) only; or passes both individual values and a map.

Related errors

• invalid canvas color: specify RGB or RGBA using hex notation
• not enough arguments: provide one or more padding values usi
• padding values must not exceed 5000 pixels
• too many padding values: received %d, expected maximum of 4
• final image width will be less than 1 pixel: check padding v

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