gohugoio/hugo · error

quality ranges from 1 to 100 inclusive

Error message

quality ranges from 1 to 100 inclusive

What it means

`DecodeImageConfig` parses the image processing option string (e.g. "200x100 q80 jpg"). When a token starts with `q`, the rest is parsed as the JPEG/WEBP quality. Quality must be between 1 and 100 inclusive; anything outside that is rejected at config.go:285.

Solutions

1. Use an integer quality from 1 to 100, e.g. `q75` (the default).
2. If you wanted default quality, just omit the `q` token.
3. Double-check the option string ordering — `q` must be followed immediately by digits.

Example fix

{{/* before */}}
{{ $img.Resize "300x q0 jpg" }}

{{/* after */}}
{{ $img.Resize "300x q75 jpg" }}

if q < 1 || q > 100 { return fmt.Errorf("quality must be 1-100, got %d", q) }

When it happens

Trigger: Using `q0`, `q101`, `q-5`, or any `qNNN` outside 1-100 in a template image action like `{{ $img.Resize "q120 jpg" }}` or `.Fill`/`.Fit`/`.Crop`.

Common situations: Typing `q0` thinking it disables quality; using a percentage like `q0.8`; copy-paste from a doc that used 0-1 floats; confusion with other tools' quality scales.

Related errors

• invalid image dimensions
• must provide Width and Height
• must provide Width or Height
• width or height are not supported for this action
• 'pager size' must be a positive integer

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

Appendix: source

Thrown at resources/images/config.go:285

			c.Filter = filter
		} else if _, ok := hints[part]; ok {
			c.Hint = part
		} else if _, ok := compressionMethods[part]; ok {
			c.Compression = part
		} else if f, ok := ImageFormatFromExt("." + part); ok {
			c.TargetFormat = f
		} else if part[0] == '#' {
			c.BgColor, err = hexStringToColorGo(part[1:])
			if err != nil {
				return c, err
			}
		} else if part[0] == 'q' {
			c.Quality, err = strconv.Atoi(part[1:])
			if err != nil {
				return c, err
			}
			if c.Quality < 1 || c.Quality > 100 {
				return c, errors.New("quality ranges from 1 to 100 inclusive")
			}
		} else if part[0] == 'r' {
			c.Rotate, err = strconv.Atoi(part[1:])
			if err != nil {
				return c, err
			}
		} else if strings.Contains(part, "x") {
			widthHeight := strings.Split(part, "x")
			if len(widthHeight) <= 2 {
				first := widthHeight[0]
				if first != "" {
					c.Width, err = strconv.Atoi(first)
					if err != nil {
						return c, err
					}
				}

				if len(widthHeight) == 2 {

View on GitHub (pinned to 52c9bd7908)