gohugoio/hugo · error

failed to %s image %q: %w

Error message

failed to %s image %q: %w

What it means

Wrapper error added in imageResource.processActionSpec in Hugo when an image processing action (resize, crop, fit, fill, filter) fails. It wraps the underlying error (bad option spec, decode failure, unsupported format) with the action name and the image's source path so the user can identify which image and operation broke.

Source

Thrown at resources/image.go:363

					orientation = meta.Orientation
				}
				if tf := orientationProvider.AutoOrient(orientation); tf != nil {
					filters = append(filters, tf)
				}
			} else {
				filters = append(filters, f)
			}
		}
		return i.Proc.Filter(src, filters...)
	})
}

func (i *imageResource) processActionSpec(action, spec string) (images.ImageResource, error) {
	options := append([]string{action}, strings.Fields(strings.ToLower(spec))...)
	ir, err := i.processOptions(options)
	if err != nil {
		if sourcePath := i.sourcePath(); sourcePath != "" {
			err = fmt.Errorf("failed to %s image %q: %w", action, sourcePath, err)
		}
		return nil, err
	}
	return ir, nil
}

func (i *imageResource) processOptions(options []string) (images.ImageResource, error) {
	conf, err := images.DecodeImageConfig(options, i.Proc.Cfg, i.Format)
	if err != nil {
		return nil, err
	}

	img, err := i.doWithImageConfig(conf, func(src image.Image) (image.Image, error) {
		return i.Proc.ApplyFiltersFromConfig(src, conf)
	})
	if err != nil {
		return nil, err
	}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Check the wrapped inner error and the reported source path to identify the failing image and action
2. Fix the option spec passed to Resize/Fit/Fill/Crop (e.g. "600x400 webp q80") per https://gohugo.io/content-management/image-processing/
3. Verify the source image opens in another tool; replace corrupt/truncated files
4. Ensure the image format is one Hugo can decode (jpg, png, gif, webp, tiff, bmp)

Example fix

// before
{{ $img := resources.Get "hero.jpg" }}
{{ $small := $img.Resize "x" }}
// after
{{ $img := resources.Get "hero.jpg" }}
{{ $small := $img.Resize "600x" }}

{{ with resources.Get "img.jpg" }}{{ if in (slice "image") (index (split .MediaType.Type "/") 0) }}...{{ end }}{{ end }}

{{ with try (.Resize "800x") }}{{ with .Err }}{{ warnf "image op failed: %s" . }}{{ else }}{{ .Value.RelPermalink }}{{ end }}{{ end }}

When it happens

Trigger: Calling .Resize/.Crop/.Fit/.Fill/.Filter/.Process on an image resource in a template with an invalid option string (e.g. bad dimensions, unknown anchor, invalid quality), or on an image whose decode fails; processOptions returns an error and it is wrapped with the action and sourcePath.

Common situations: Typos in resize specs like `{{ $img.Resize "x" }}`, unsupported target formats, corrupt or truncated image files in assets/, EXIF/format edge cases, or processing an SVG/unsupported format as a raster image.

Related errors

• error building site: %w
• failed to detect format from content
• failed to detect target data serialization format
• templates.Defer cannot be used inside a partialCached partia
• Defer does not take any arguments

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