gohugoio/hugo · error

final image width will be less than 1 pixel: check padding v

Error message

final image width will be less than 1 pixel: check padding values

What it means

Thrown by the padding filter's Draw when the resulting canvas width is less than 1 pixel (padding.go:32-37). Width = source width + left + right; with negative padding (cropping) that exceeds the source width, the canvas becomes non-positive and the filter aborts.

Source

Thrown at resources/images/padding.go:36

	"image/color"
	"image/draw"

	"github.com/gohugoio/gift"
)

var _ gift.Filter = (*paddingFilter)(nil)

type paddingFilter struct {
	top, right, bottom, left int
	ccolor                   color.Color // canvas color
}

func (f paddingFilter) Draw(dst draw.Image, src image.Image, options *gift.Options) {
	w := src.Bounds().Dx() + f.left + f.right
	h := src.Bounds().Dy() + f.top + f.bottom

	if w < 1 {
		panic("final image width will be less than 1 pixel: check padding values")
	}
	if h < 1 {
		panic("final image height will be less than 1 pixel: check padding values")
	}

	i := image.NewRGBA(image.Rect(0, 0, w, h))
	draw.Draw(i, i.Bounds(), image.NewUniform(f.ccolor), image.Point{}, draw.Src)
	gift.New().Draw(dst, i)
	gift.New().DrawAt(dst, src, image.Pt(f.left, f.top), gift.OverOperator)
}

func (f paddingFilter) Bounds(srcBounds image.Rectangle) image.Rectangle {
	return image.Rect(0, 0, srcBounds.Dx()+f.left+f.right, srcBounds.Dy()+f.top+f.bottom)
}

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Clamp negative padding so |left + right| < source width (and leave at least 1px).
2. Use images.Crop for intentional cropping instead of negative padding.
3. Validate image dimensions before applying aggressive negative padding.

Example fix

// before
{{ $filters = $filters | append (images.Padding -100 -100) }}
// after
{{ $filters = $filters | append (images.Crop "20x20 Center") }}

{{ $w := $img.Width }}
{{ if le (add $w (add $left $right)) 0 }}
  {{ errorf "negative padding exceeds image width %d" $w }}
{{ end }}

When it happens

Trigger: Passing negative padding whose magnitude exceeds the image width, e.g. a 50px-wide image with left=-100, right=-100. Negative values crop; over-cropping destroys the canvas.

Common situations: Using padding to crop dynamically without clamping to image dimensions; applying a fixed negative padding to a set of images of varying widths.

Related errors

• final image height will be less than 1 pixel: check padding
• the padding filter requires between 1 and 5 arguments
• 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

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