gohugoio/hugo · critical

webp codec is not available

Error message

webp codec is not available

What it means

`NewImageProcessor` initializes the WASM-backed WebP codec via `wasmDispatchers.NewWepCodec()`. If that returns a nil codec (no error but no implementation), image processing cannot function and startup fails at image.go:153. WebP encode/decode is core to Hugo's image pipeline.

Solutions

1. Use an official Hugo release binary where the WebP WASM codec is embedded.
2. If building Hugo from source, ensure the WASM dispatcher assets are present and the build tags include the webp codec.
3. Re-download/reinstall Hugo to restore the embedded WASM binary if it was corrupted.

proc, err := images.NewImageProcessor(...)
if err != nil {
    if strings.Contains(err.Error(), "webp codec is not available") {
        // fall back to an official Hugo binary with embedded WASM codec
    }
    return err
}

When it happens

Trigger: Hugo build startup when the embedded WASM WebP dispatcher cannot be instantiated and returns nil. This is a hard failure during `NewImageProcessor`, before any image is processed.

Common situations: Running a custom/trimmed Hugo build with the WebP WASM asset excluded; a corrupted or missing embedded WASM binary; platform/build constraints that disable the webp dispatcher; downgrading to a build predating the v0.153.0 WebP rework.

Related errors

• format not supported
• gif: number of frame durations does not match number of…
• imaging.webp.compression must be one of lossy or lossless…
• imaging.webp.hint must be one of picture, photo, drawing…
• imaging.webp.method must be between 0 and 6, got

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

Appendix: source

Thrown at resources/images/image.go:153

		return nil, err
	}

	m := cfg.Config.Imaging.Meta
	metaDecoder, err := meta.NewDecoder(
		meta.WithFields(m.Fields),
		meta.WithSources(m.Sources...),
		meta.WithWarnLogger(warnl),
	)
	if err != nil {
		return nil, err
	}

	webpCodec, err := wasmDispatchers.NewWepCodec()
	if err != nil {
		return nil, err
	}
	if webpCodec == nil {
		return nil, errors.New("webp codec is not available")
	}
	avifCodec, err := wasmDispatchers.NewAvifCodec()
	if err != nil {
		return nil, err
	}
	imageCodec := newCodec(webpCodec, avifCodec, debugl)

	return &ImageProcessor{
		Cfg:         cfg,
		exifDecoder: exifDecoder,
		metaDecoder: metaDecoder,
		Codec:       imageCodec,
	}, nil
}

type ImageProcessor struct {
	Cfg         *config.ConfigNamespace[ImagingConfig, ImagingConfigInternal]
	exifDecoder *meta.Decoder

View on GitHub (pinned to 52c9bd7908)