gohugoio/hugo · error

failed to image

Error message

failed to %s image %q: %w

What it means

Returned by imageResource.processActionSpec when processing options for Resize/Crop/Fit/Fill/Process fails. It wraps the underlying error (from DecodeImageConfig or doWithImageConfig) and prepends the action verb and the source file path for diagnostics. This is the top-level error for any image transformation invoked via the spec-string API.

Solutions

1. Read the wrapped error -- it pinpoints whether DecodeImageConfig (spec parsing) or doWithImageConfig (actual processing) failed.
2. Fix the spec string: valid anchors (Center, TopLeft, smart), valid NxM dimensions, q1-100 quality.
3. If the source image is corrupt, replace it or exclude it from processing.
4. For smartcrop silent failures, note the code falls back to Center fill automatically (issue 7955).

Example fix

// before
{{ $img := (.Resize "300xTopleft") }}

// after: correct anchor spelling
{{ $img := (.Resize "300x TopLeft") }}

// Validate spec string before calling Resize/Crop/Fill.
var validSpecAnchors = map[string]bool{"center": true, "topleft": true, "top": true, "topright": true, "left": true, "right": true, "bottomleft": true, "bottom": true, "bottomright": true, "smart": true}
func checkSpec(spec string) error {
    for _, tok := range strings.Fields(strings.ToLower(spec)) {
        if strings.HasPrefix(tok, "q") { /* parse 1-100 */ }
        if strings.HasPrefix(tok, "#") { /* valid hex */ }
        if strings.Contains(tok, "x") { /* NxM */ }
        if !validSpecAnchors[tok] && !validFilters[tok] { /* unknown token */ }
    }
    return nil
}

if _, err := img.Resize(spec); err != nil {
    var pe *os.PathError
    if errors.As(err, &pe) { /* decode/processing failure on the file */ }
    return err
}

When it happens

Trigger: Calling .Resize("300x"), .Crop("200x200 Foo"), .Fill("100x100 smart") etc. where the spec string is malformed (unknown anchor, bad dimensions, invalid quality) or where the actual filter application fails (corrupt source image, unsupported format, out-of-memory).

Common situations: A typo in a spec string (e.g. "300xTopleft"), an unsupported resample filter name, a quality value out of range, a corrupted source image that decodes but fails to process, or smartcrop failing silently on degenerate images.

Related errors

• cannot transform content of Resource of type %T
• failed to add internal partial decorator template
• failed to create internal partial decorator template
• failed to create page from pageMetaSource
• failed to create term page

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

Appendix: 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 52c9bd7908)