gohugoio/hugo · error

invalid image dimensions

Error message

invalid image dimensions

What it means

When a token in the option string contains 'x', Hugo splits it into width and height. More than one 'x' (three or more segments) makes the dimension spec unparseable, so Hugo fails rather than guessing.

Source

Thrown at resources/images/config.go:313

				first := widthHeight[0]
				if first != "" {
					c.Width, err = strconv.Atoi(first)
					if err != nil {
						return c, err
					}
				}

				if len(widthHeight) == 2 {
					second := widthHeight[1]
					if second != "" {
						c.Height, err = strconv.Atoi(second)
						if err != nil {
							return c, err
						}
					}
				}
			} 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")
		}
	}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Fix the dimension token to WIDTHxHEIGHT, WIDTHx, or xHEIGHT (e.g. "600x400", "600x").
2. If building the string dynamically, ensure options are space-separated: printf "%dx%d webp" $w $h.
3. Check for stray tokens containing 'x' that were meant to be something else.

Example fix

<!-- before -->
{{ $img.Fill "600x400x2" }}
<!-- after -->
{{ $img.Fill "600x400" }}

if w < 0 || h < 0 {
    return errors.New("width and height must be non-negative")
}

When it happens

Trigger: A dimensions token like "100x200x300" in .Resize/.Fill/.Fit options — strings.Split on "x" yields more than two parts.

Common situations: Concatenation bugs when building the option string in templates (e.g. joining two size specs without a space); copy-paste errors; accidentally including an 'x'-containing word that isn't a recognized action/anchor/filter so it's parsed as dimensions.

Related errors

• quality ranges from 1 to 100 inclusive
• must provide Width and Height
• must provide Width or Height
• width or height are not supported for this action
• 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/61a85242a1f75194.json. Report an issue: GitHub ↗.