What causes "failed to decode image: %s" in gohugoio/hugo?

Confirm the overlay resource is a valid decodable image.

failed to decode image: %s

Error message

failed to decode image: %s

What it means

Thrown by the overlay filter's Draw when the overlay source image cannot be decoded (overlay.go:32-35). Identical mechanism to the mask decode error: DecodeImage returns an error and the filter panics with the underlying message.

Source

Thrown at resources/images/overlay.go:34

import (
	"fmt"
	"image"
	"image/draw"

	"github.com/gohugoio/gift"
)

var _ gift.Filter = (*overlayFilter)(nil)

type overlayFilter struct {
	src  ImageSource
	x, y int
}

func (f overlayFilter) Draw(dst draw.Image, src image.Image, options *gift.Options) {
	overlaySrc, err := f.src.DecodeImage()
	if err != nil {
		panic(fmt.Sprintf("failed to decode image: %s", err))
	}

	gift.New().Draw(dst, src)
	gift.New().DrawAt(dst, overlaySrc, image.Pt(f.x, f.y), gift.OverOperator)
}

func (f overlayFilter) Bounds(srcBounds image.Rectangle) image.Rectangle {
	return image.Rect(0, 0, srcBounds.Dx(), srcBounds.Dy())
}

View on GitHub (pinned to 52c9bd7908)

Solutions

Confirm the overlay resource is a valid decodable image.
Validate the resource loads before composing the overlay filter.
Replace corrupt or wrong-format overlay assets.

Example fix

// before
{{ $logo := resources.GetRemote "https://example.com/logo" }}
{{ $filters = $filters | append (images.Overlay $logo 0 0) }}
// after
{{ $logo := resources.Get "brand/logo.png" }}
{{ $filters = $filters | append (images.Overlay $logo 0 0) }}

Defensive patterns

Strategy: validation

Validate before calling

{{ with $overlay }}
  {{ if reflect.IsImageResource . }}
    {{ $filters = $filters | append (images.Overlay . 0 0) }}
  {{ else }}
    {{ errorf "overlay is not a processable image" }}
  {{ end }}
{{ end }}

Prevention

Confirm overlay assets are valid raster images.
Validate remote overlays loaded successfully before composing.
Cache overlay assets locally to avoid repeated decode failures.

When it happens

Trigger: Calling images.Overlay with a src resource that fails to decode — corrupt bytes, unsupported format, empty file, or non-image content masquerading as an image resource.

Common situations: Watermark/logo resource is missing or corrupt; remote overlay fetch returned an error page; format unsupported by the image decoder.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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