gohugoio/hugo · error

webp: image is too large to encode

Error message

webp: image is too large to encode

What it means

Returned by WebpCodec.Encode (internal/warpc/webp.go:241-242) before dispatching to the WASM libwebp encoder. The WebP format itself caps dimensions at 16383×16383, and Hugo rejects anything with a width or height of 65536+ up front (with libwebp enforcing the tighter limit); the check fails fast instead of letting the encoder produce a broken file.

Source

Thrown at internal/warpc/webp.go:242

			Source: bytes.NewReader(b),
		},
	}

	out, err := dd.Execute(context.Background(), message)
	if err != nil {
		return image.Config{}, err
	}
	return image.Config{
		Width:      out.Data.Params.Width,
		Height:     out.Data.Params.Height,
		ColorModel: color.RGBAModel,
	}, nil
}

func (d *WebpCodec) Encode(w io.Writer, img image.Image, opts map[string]any) error {
	b := img.Bounds()
	if b.Dx() >= 1<<16 || b.Dy() >= 1<<16 {
		return errors.New("webp: image is too large to encode")
	}

	dd, err := d.d()
	if err != nil {
		return err
	}

	const (
		commandEncodeNRGBA = "encodeNRGBA"
		commandEncodeGray  = "encodeGray"
	)

	var (
		bounds         = img.Bounds()
		imageBytes     []byte
		stride         int
		frameDurations []int
		loopCount      int

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Resize the image below the WebP limit before/while converting: {{ $img := $img.Resize "16000x webp" }} (WebP's real cap is 16383 per side).
2. Keep oversized assets in a format without the limit (PNG/JPEG/AVIF) instead of WebP.
3. Check your resize arguments for typos producing absurd target dimensions.

Example fix

// before (layouts/page.html)
{{ $out := $huge.Process "webp" }}
// after
{{ $out := $huge.Process "resize 16000x webp" }}

const webpMax = 16383 // WebP hard limit per dimension
if cfg.Width > webpMax || cfg.Height > webpMax {
    // resize first or choose another target format
}

When it happens

Trigger: Encoding an image to WebP via Hugo's image processing (.Resize/.Process/.Fill with target format webp, or images.Config webp output) where the source or target bounds have Dx() or Dy() ≥ 65536 — e.g. converting an enormous panorama or a giant sprite sheet.

Common situations: Huge scanned images, stitched panoramas, or map tiles converted to WebP; automated pipelines that pass original camera/scan resolution straight into WebP output; accidentally multiplying dimensions in a resize spec (e.g. "x" filter args swapped).

Related errors

• webp: animated image has no frames
• errSeqSizeExceedsLimit
• the number of requested values (%v) must be a non-negative i
• webp codec is not available
• gif: number of frame durations does not match number of fram

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/8e937ad1d71f2e5f.json. Report an issue: GitHub ↗.