gohugoio/hugo · critical

webp codec is not available

Error message

webp codec is not available

What it means

NewImageProcessor obtains Hugo's WebP encoder/decoder from a WASM dispatcher (wasmDispatchers.NewWepCodec); since v0.153.0 WebP support is provided via an embedded WebAssembly codec. If the dispatcher returns a nil codec, the processor cannot be constructed and site build setup fails with this error. It signals the runtime environment could not provide the WASM-backed WebP codec at all.

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 8a468df065)

Solutions

1. Install an official Hugo extended release binary from gohugo.io/GitHub releases rather than a distro or self-built variant.
2. Upgrade to the latest Hugo version so the WASM codec dispatch matches the current code path.
3. If building from source, build with the standard `go build` flags used by the release process (no codec-stripping tags).
4. Report the platform/build details upstream if an official binary reproduces it.

// Check webp support in this build before requesting .webp output
supported := map[string]bool{"jpg": true, "jpeg": true, "png": true, "gif": true, "tif": true, "bmp": true, "webp": webpAvailable}
if !supported[strings.ToLower(targetFormat)] {
    return fmt.Errorf("target format %q not available in this build", targetFormat)
}

if err != nil && strings.Contains(err.Error(), "webp codec is not available") {
    // build lacks webp encoding (extended build required) — fall back to png/jpg only if explicitly configured
}

When it happens

Trigger: Hugo startup/site initialization where the warpc WASM dispatchers fail to yield a WebP codec — typically a Hugo binary built without the embedded codec support or an environment where the wazero WASM runtime cannot instantiate the module.

Common situations: Custom or third-party Hugo builds compiled with unusual build tags; heavily sandboxed or exotic platforms where WASM instantiation fails; version mismatches after the v0.153.0 codec rework.

Related errors

• config needs a filename
• must provide an image and one or more filters
• cannot encode an empty string
• error correction level must be one of low, medium, quartile,
• scale must be an integer greater than or equal to 2

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