{"id":"559cd535a6238bfe","repo":"gohugoio/hugo","slug":"webp-codec-is-not-available","errorCode":null,"errorMessage":"webp codec is not available","messagePattern":"webp codec is not available","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"resources/images/image.go","lineNumber":153,"sourceCode":"\t\treturn nil, err\n\t}\n\n\tm := cfg.Config.Imaging.Meta\n\tmetaDecoder, err := meta.NewDecoder(\n\t\tmeta.WithFields(m.Fields),\n\t\tmeta.WithSources(m.Sources...),\n\t\tmeta.WithWarnLogger(warnl),\n\t)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\twebpCodec, err := wasmDispatchers.NewWepCodec()\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tif webpCodec == nil {\n\t\treturn nil, errors.New(\"webp codec is not available\")\n\t}\n\tavifCodec, err := wasmDispatchers.NewAvifCodec()\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\timageCodec := newCodec(webpCodec, avifCodec, debugl)\n\n\treturn &ImageProcessor{\n\t\tCfg:         cfg,\n\t\texifDecoder: exifDecoder,\n\t\tmetaDecoder: metaDecoder,\n\t\tCodec:       imageCodec,\n\t}, nil\n}\n\ntype ImageProcessor struct {\n\tCfg         *config.ConfigNamespace[ImagingConfig, ImagingConfigInternal]\n\texifDecoder *meta.Decoder","sourceCodeStart":135,"sourceCodeEnd":171,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/resources/images/image.go#L135-L171","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install an official Hugo extended release binary from gohugo.io/GitHub releases rather than a distro or self-built variant.","Upgrade to the latest Hugo version so the WASM codec dispatch matches the current code path.","If building from source, build with the standard `go build` flags used by the release process (no codec-stripping tags).","Report the platform/build details upstream if an official binary reproduces it."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Check webp support in this build before requesting .webp output\nsupported := map[string]bool{\"jpg\": true, \"jpeg\": true, \"png\": true, \"gif\": true, \"tif\": true, \"bmp\": true, \"webp\": webpAvailable}\nif !supported[strings.ToLower(targetFormat)] {\n    return fmt.Errorf(\"target format %q not available in this build\", targetFormat)\n}","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"webp codec is not available\") {\n    // build lacks webp encoding (extended build required) — fall back to png/jpg only if explicitly configured\n}","preventionTips":["Use the extended Hugo build when webp encoding is required","Feature-detect codec availability at startup and fail fast with a clear message","Document the required build variant in project setup docs and CI"],"tags":["hugo","webp","wasm","startup","images"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}