gohugoio/hugo · error

final image height will be less than 1 pixel: check padding

Error message

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

What it means

Thrown by the padding filter's Draw when the resulting canvas height is less than 1 pixel (padding.go:33-40). Height = source height + top + bottom; over-aggressive negative vertical padding drives the canvas non-positive.

Source

Thrown at resources/images/padding.go:39

	"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. Ensure |top + bottom| < source height with at least 1px remaining.
2. Prefer images.Crop for vertical cropping.
3. Clamp negative values to the image dimensions.

Example fix

// before
{{ $filters = $filters | append (images.Padding -200 0 -200 0) }}
// after
{{ $filters = $filters | append (images.Crop "10x40 Center") }}

{{ $h := $img.Height }}
{{ if le (add $h (add $top $bottom)) 0 }}
  {{ errorf "negative padding exceeds image height %d" $h }}
{{ end }}

When it happens

Trigger: Passing top/bottom negative padding whose combined magnitude meets or exceeds the source height, e.g. a 30px-tall image with top=-50.

Common situations: Dynamic negative padding applied uniformly to images of differing heights; attempting to crop vertically via padding without bounds checking.

Related errors

• final image width will be less than 1 pixel: check padding v
• 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/3855f3d1352b0fd4. Report an issue: GitHub.