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.