invalid canvas color: specify RGB or RGBA using hex notation

Error message

invalid canvas color: specify RGB or RGBA using hex notation

What it means

Thrown by images.Padding when the trailing argument is parsed as a color and parsing returns a hard error (filters.go:158-161) — i.e. the value looked color-like enough to attempt parsing but was malformed. Valid formats are RGB/RGBA hex (3, 4, 6, or 8 hex digits, optional leading #).

Source

Thrown at resources/images/filters.go:160

// 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")
		}
	}

	var vals []int
	for _, v := range args {
		vi := cast.ToInt(v)
		if vi > 5000 {
			panic("padding values must not exceed 5000 pixels")
		}
		vals = append(vals, vi)
	}

	switch len(args) {

View on GitHub (pinned to 52c9bd7908)

Solutions

Use a valid hex color: RRGGBB or RRGGBBAA (or shorthand RGB/RGBA), optionally prefixed with #.
Strip whitespace from dynamically generated color strings.
Avoid named CSS colors; convert them to hex first.

Example fix

// before
{{ $filters = $filters | append (images.Padding 10 "#ZZZ") }}
// after
{{ $filters = $filters | append (images.Padding 10 "0000ffff") }}

Defensive patterns

Strategy: validation

Validate before calling

{{ $color := .color | default "ffffff" }}
{{ if not (findRE `^[0-9a-fA-F]{3,4}$|^[0-9a-fA-F]{6}$|^[0-9a-fA-F]{8}$` (trimPrefix "#" $color)) }}
  {{ errorf "invalid canvas color %q" $color }}
{{ end }}

Prevention

Validate hex color format (3/4/6/8 hex digits) before passing.
Strip a leading # consistently.
Avoid named CSS colors.

When it happens

Trigger: Passing a canvas color like "#GGG", "12345", "ff0000ff00", or a non-hex string in the trailing slot. Note: a value that cannot be stringified returns ok=false (no panic); only an actual parse error triggers this.

Common situations: Typos in hex color, copying colors with alpha in the wrong position, using named CSS colors ("red") which the parser does not accept, or trailing whitespace/newline in the color string.

Related errors

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