gohugoio/hugo · error

WebPAnimEncoderAdd failed for final frame\n

Error message

WebPAnimEncoderAdd failed for final frame\n

What it means

Printed by genwebp's encodeNRGBAAnimated (webp.c:254) when the final flush call WebPAnimEncoderAdd(enc, NULL, timestamp, config) returns false. libwebp uses a NULL picture to signal end-of-animation and to let the encoder finalize internal state; failure here usually indicates the prior frames left the encoder in a bad state, the WebPConfig is internally inconsistent, or memory is exhausted during finalization. The worker deletes the encoder and returns NULL.

Source

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

            WebPPictureFree(&pic);
            WebPAnimEncoderDelete(enc);
            return NULL;
        }

        if (!WebPAnimEncoderAdd(enc, &pic, timestamp, config))
        {
            fprintf(stderr, "WebPAnimEncoderAdd failed\n");
            WebPPictureFree(&pic);
            WebPAnimEncoderDelete(enc);
            return NULL;
        }
        timestamp += params.frameDurations[i];
        WebPPictureFree(&pic);
    }

    if (!WebPAnimEncoderAdd(enc, NULL, timestamp, config))
    {
        fprintf(stderr, "WebPAnimEncoderAdd failed for final frame\n");
        WebPAnimEncoderDelete(enc);
        return NULL;
    }

    WebPData webp_data_out;
    WebPDataInit(&webp_data_out);
    if (!WebPAnimEncoderAssemble(enc, &webp_data_out))
    {
        fprintf(stderr, "WebPAnimEncoderAssemble failed\n");
        WebPAnimEncoderDelete(enc);
        return NULL;
    }
    WebPAnimEncoderDelete(enc);

    *output_size = webp_data_out.size;
    uint8_t *webp_data = malloc(*output_size);
    if (webp_data == NULL)
    {

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Reproduce with the same input on a different libwebp version to rule out a library bug.
2. Reduce animation size (frame count or canvas) to lower finalization memory pressure.
3. Rebuild genwebp against a current libwebp release.
4. Free memory in the worker before finalization (close any held decoder handles).
5. Fall back to a per-frame static WebP output if animated finalization persistently fails for this input.

Example fix

// before: huge animation finalizes OOM
enc.Encode(hugeFrames) // WebPAnimEncoderAdd failed for final frame

// after: cap animation size and skip if exceeded
const maxAnimPixels = 50_000_000
if w*h*frameCount > maxAnimPixels {
    return writeStaticFallback(firstFrame)
}
enc.Encode(hugeFrames)

const maxAnimPixels = 50_000_000
func shouldAnimate(w, h, frames int) bool {
    return w*h*frames <= maxAnimPixels
}

When it happens

Trigger: The loop completed without error but finalization fails: WebPConfig fields drift between frames (the same config pointer is reused, so this is unlikely unless mutated), an internal encoder state corruption, or memory exhaustion at the finalization step.

Common situations: Very large animations where finalization needs to allocate a big consolidated buffer, an earlier WebPAnimEncoderAdd that returned true but left partial state, or a libwebp build with a known finalization bug.

Related errors

• Error creating WebPAnimEncoder\n
• WebPAnimEncoderAssemble failed\n
• malloc failed for final webp data\n
• WebPEncode failed: %d (%s)\n
• WebPPictureImportRGBA failed\n

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