gohugoio/hugo · error

width or height are not supported for this action

Error message

width or height are not supported for this action

What it means

Actions other than crop/fill/fit/resize (e.g. plain processing/format conversion via images.Process, or filters) operate on the image at its original size. Hugo rejects width/height tokens there to fail fast on options that would be silently ignored.

Source

Thrown at resources/images/config.go:329

				}
			} else {
				return c, errors.New("invalid image dimensions")
			}
		}
	}

	switch c.Action {
	case ActionCrop, ActionFill, ActionFit:
		if c.Width == 0 || c.Height == 0 {
			return c, errors.New("must provide Width and Height")
		}
	case ActionResize:
		if c.Width == 0 && c.Height == 0 {
			return c, errors.New("must provide Width or Height")
		}
	default:
		if c.Width != 0 || c.Height != 0 {
			return c, errors.New("width or height are not supported for this action")
		}
	}

	if err := c.init(defaults.Config, sourceFormat); err != nil {
		return c, err
	}

	if mainImageVersionNumber > 0 {
		options = append(options, strconv.Itoa(mainImageVersionNumber))
	}

	if v := formatVersionNumbers[c.TargetFormat]; v > 0 {
		options = append(options, "tfv"+strconv.Itoa(v))
	}

	usesSmartCrop := c.Anchor == SmartCropAnchor && (c.Action == ActionCrop || c.Action == ActionFill)
	if smartCropVersionNumber > 0 && usesSmartCrop {
		options = append(options, strconv.Itoa(smartCropVersionNumber))

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Remove the WIDTHxHEIGHT token from the option string for this action.
2. If you want to resize AND convert, include the action in Process: {{ $img.Process "resize 600x400 webp" }}.
3. Alternatively chain calls: {{ ($img.Resize "600x400").Process "webp" }}.

Example fix

<!-- before -->
{{ $img.Process "600x400 webp" }}
<!-- after -->
{{ $img.Process "resize 600x400 webp" }}

if action == "" && (w > 0 || h > 0) {
    return errors.New("dimensions not allowed for this action")
}

When it happens

Trigger: {{ $img.Process "600x400 webp" }} or any non-resizing action whose option string contains a dimensions token — the parser sets Width/Height, then the default switch branch rejects them.

Common situations: Assuming images.Process accepts sizes like Resize does; copying an option string from a .Fill call into a .Process/.Filter call; a stray 'x'-containing token being parsed as dimensions.

Related errors

• quality ranges from 1 to 100 inclusive
• invalid image dimensions
• must provide Width and Height
• must provide Width or Height
• imaging.quality must be between 1 and 100 inclusive, got %d

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