What causes "quality ranges from 1 to 100 inclusive" in gohugoio/hugo?

Change the q token to a value between 1 and 100, e.g. q75.

quality ranges from 1 to 100 inclusive

Error message

quality ranges from 1 to 100 inclusive

What it means

Hugo parses image-processing option strings (e.g. from .Resize/.Fill/.Fit template calls) and treats any token starting with 'q' as a quality spec. After strconv.Atoi succeeds, the value is range-checked; anything outside 1–100 is rejected because JPEG/WebP/AVIF encoders only accept that range.

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 8a468df065)

Solutions

Change the q token to a value between 1 and 100, e.g. q75.
Omit the q option entirely to fall back to imaging.quality from site config.
If the quality is computed in a template, clamp it: {{ math.Max 1 (math.Min 100 $q) }}.

Example fix

<!-- before -->
{{ $img := $img.Resize "600x q0" }}
<!-- after -->
{{ $img := $img.Resize "600x q75" }}

Defensive patterns

Strategy: validation

Validate before calling

if q < 1 || q > 100 {
    return fmt.Errorf("quality %d out of range [1,100]", q)
}

Prevention

Clamp or validate quality (q1–q100 in the spec string) before building the image processing spec
In templates, only pass literal qN values in the 1–100 range
Centralize image option construction in one helper so the range check lives in one place

When it happens

Trigger: Calling {{ $img.Resize "300x q0" }}, "q101", "q150", or any qN option with N < 1 or N > 100 in a Resize/Fill/Fit/Crop/Filter option string or in Markdown image render hooks that forward such options.

Common situations: Typos like q1000 instead of q100; templates computing quality dynamically (e.g. from front matter) that produce 0; confusing 0 as 'default' when the way to get the default is to omit q entirely.

Related errors

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