gohugoio/hugo · error

failed to open image for decode: %w

Error message

failed to open image for decode: %w

What it means

Raised by imageResource.DecodeImage when i.ReadSeekCloser() fails, i.e. Hugo cannot open the underlying image file/stream before decoding it for a processing operation. It wraps the filesystem or resource-open error; the decode itself never starts.

Source

Thrown at resources/image.go:475

		targetPath := i.relTargetPathFromConfig(conf, i.getSpec().Imaging.Cfg.SourceHash)
		ci.setTargetPath(targetPath)
		ci.Format = conf.TargetFormat
		ci.setMediaType(conf.TargetFormat.MediaType())

		return ci, converted, nil
	})
	if err != nil {
		return nil, err
	}
	return img, nil
}

// DecodeImage decodes the image source into an Image.
// This for internal use only.
func (i *imageResource) DecodeImage() (image.Image, error) {
	f, err := i.ReadSeekCloser()
	if err != nil {
		return nil, fmt.Errorf("failed to open image for decode: %w", err)
	}
	defer f.Close()

	return i.getSpec().Imaging.Codec.DecodeFormat(i.Format, f)
}

func (i *imageResource) clone(img image.Image) *imageResource {
	spec := i.baseResource.Clone().(baseResource)

	var image *images.Image
	if img != nil {
		image = i.WithImage(img)
	} else {
		image = i.WithSpec(spec)
	}

	ir := &imageResource{
		Image:        image,

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Inspect the wrapped error for the OS-level cause (ENOENT, EACCES) and confirm the file exists at the expected path
2. Fix file permissions or restore the missing/placeholder file (force cloud-sync download)
3. Restart `hugo server` if files changed on disk mid-build
4. Check module/mount configuration if the image comes from a mounted or module filesystem

{{ $img := resources.Get "photo.jpg" }}{{ if and $img (eq (index (split $img.MediaType.Type "/") 0) "image") }}{{/* safe to decode */}}{{ end }}

{{ with try ($img.Resize "400x") }}{{ with .Err }}{{ errorf "decode failed for %s: %s" $img.Name . }}{{ end }}{{ end }}

When it happens

Trigger: Any image transform (Resize, Fill, Filter, etc.) triggers doWithImageConfig → DecodeImage; the error fires when opening the source via ReadSeekCloser fails — file deleted/moved mid-build, permission denied, or a broken mounted/remote resource backing the image.

Common situations: Files removed while the dev server rebuilds, broken symlinks in assets/, permission problems in CI/containers, cloud-synced folders (Dropbox/OneDrive placeholders) where the file isn't actually on disk, or exhausted file descriptors on very large sites.

Related errors

• failed to read archetype file: %w
• %q is not a directory
• walk: stat: %s
• walk: Readdir: %w
• failed to save file %q:: %w

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