gohugoio/hugo · error

WebPEncode failed: %d (%s)\n

Error message

WebPEncode failed: %d (%s)\n

What it means

Printed by genwebp's encodeNRGBA (webp.c:133) when WebPEncode returns 0. The error_code on the WebPPicture is translated through kErrorMessages and printed alongside the numeric code. This is the umbrella failure for the actual VP8 encoding step; the most common codes are BAD_DIMENSION (width or height > 16383), OUT_OF_MEMORY, BITSTREAM_OUT_OF_MEMORY, INVALID_CONFIGURATION, or FILE_TOO_BIG (>4GB output). The function returns NULL and the Go host sees 'Error encoding NRGBA to WebP'.

Source

Thrown at internal/warpc/genwebp/webp.c:133

    if (!WebPPictureInit(&pic))
    {
        fprintf(stderr, "WebPPictureInit failed\n");
        return NULL;
    }

    pic.use_argb = 1;
    pic.width = width;
    pic.height = height;
    pic.writer = WebPMemoryWrite;
    pic.custom_ptr = &wrt;
    WebPMemoryWriterInit(&wrt);
    ok = WebPPictureImportRGBA(&pic, rgba, stride);
    if (ok)
    {
        ok = WebPEncode(config, &pic);
        if (!ok)
        {
            fprintf(stderr, "WebPEncode failed: %d (%s)\n", pic.error_code, kErrorMessages[pic.error_code]);
        }
    }
    else
    {
        fprintf(stderr, "WebPPictureImportRGBA failed: %d (%s)\n", pic.error_code, kErrorMessages[pic.error_code]);
    }
    WebPPictureFree(&pic);
    if (!ok)
    {
        WebPMemoryWriterClear(&wrt);
        return NULL;
    }
    *output_size = wrt.size;
    return wrt.mem;
}

static uint8_t *encodeGray(WebPConfig *config, uint8_t *y, int width, int height, int stride, size_t *output_size)
{

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Cap input dimensions in the Go host before encoding: if width > 16383 || height > 16383, downscale first or skip WebP and fall back to another format.
2. Map the numeric error_code to its message (BAD_DIMENSION vs OUT_OF_MEMORY) to choose the right fix; the printed text tells you which.
3. Lower `quality` or `method` for very large frames to avoid FILE_TOO_BIG / OOM.
4. Validate WebPConfig fields before calling WebPEncode (quality 0-100, method 0-6, preset valid).
5. Raise the container/cgroup memory limit if the error is consistently OUT_OF_MEMORY on moderate images.

Example fix

// before: WebPEncode failed BAD_DIMENSION on a 18000px source
img := load(path) // 18000 x 6000
encodeWebp(img)

// after: clamp to WebP's 16383 limit
const maxWH = 16383
if img.Bounds().Dx() > maxWH || img.Bounds().Dy() > maxWH {
    img = resizeKeepingAspect(img, maxWH)
}
encodeWebp(img)

// Reject images that exceed WebP's dimension cap before encoding.
const webpMaxDim = 16383
func canEncodeWebp(w, h int) error {
    if w <= 0 || h <= 0 { return fmt.Errorf("invalid dimensions %dx%d", w, h) }
    if w > webpMaxDim || h > webpMaxDim {
        return fmt.Errorf("dimension %dx%d exceeds WebP cap %d", w, h, webpMaxDim)
    }
    return nil
}

When it happens

Trigger: Encoding an image larger than 16383 pixels on either edge, encoding at very high quality/resolution that pushes the encoded output near 4GB, providing a WebPConfig with an invalid combination of fields (quality out of range, method > 6, lossless preset conflict), or running out of memory on a large frame.

Common situations: User uploads a huge source image (e.g. a 20000px panorama) and Hugo's resize still leaves a dimension over the WebP cap; very high `quality` setting combined with a large image; running in a memory-limited container; or a hint/compression preset that resolves to an invalid WebPConfig in initEncoderConfig.

Related errors

• Error creating WebPAnimEncoder\n
• WebPAnimEncoderAssemble failed\n
• WebPPictureInit failed\n
• WebPPictureImportRGBA failed: %d (%s)\n
• WebPAnimEncoderAdd failed for final frame\n

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