imaging.jpeg.quality must be between 1 and 100 inclusive, go

Error message

imaging.jpeg.quality must be between 1 and 100 inclusive, got %d

What it means

JpegConfig.init resolves the effective JPEG quality: explicit imaging.jpeg.quality, else the global imaging.quality, else 75. The resolved value must be 1–100 for the JPEG encoder; anything else is rejected at config load.

Source

Thrown at resources/images/config.go:665

	// Default is ["exif", "iptc"] (XMP is excluded for performance reasons).
	Sources []string
}

// JpegConfig holds JPEG-specific encoding configuration.
type JpegConfig struct {
	// Quality setting (1-100). Falls back to the global imaging.quality if unset.
	Quality int
}

func (c *JpegConfig) init(ic *ImagingConfig) error {
	if c.Quality == 0 {
		c.Quality = ic.Quality
	}
	if c.Quality == 0 {
		c.Quality = 75
	}
	if c.Quality < 1 || c.Quality > 100 {
		return fmt.Errorf("imaging.jpeg.quality must be between 1 and 100 inclusive, got %d", c.Quality)
	}
	return nil
}

// AvifConfig holds AVIF-specific encoding configuration.
type AvifConfig struct {
	// Quality setting (1-100). Falls back to the global imaging.quality if unset.
	Quality int

	// Compression method to use.
	// One of "lossy" or "lossless".
	Compression string

	// Hint about what type of image this is. Used for chroma subsampling.
	// Valid values are "picture", "photo", "drawing", "icon", or "text".
	// Default is "photo".
	Hint string

View on GitHub ↗ (pinned to 8a468df065)

Solutions

Set imaging.jpeg.quality in hugo.toml to a value between 1 and 100.
Remove the setting to inherit imaging.quality or the default of 75.
If you meant to control quality per-call, use the qN option in the template instead.

Example fix

# before (hugo.toml)
[imaging.jpeg]
quality = 850
# after
[imaging.jpeg]
quality = 85

Defensive patterns

Strategy: validation

Validate before calling

if q := cfg.Imaging.JPEG.Quality; q != 0 && (q < 1 || q > 100) {
    return fmt.Errorf("imaging.jpeg.quality must be 1-100, got %d", q)
}

Prevention

Validate format-specific quality overrides ([imaging.jpeg]) with the same 1–100 rule as the global quality
Run a CI hugo build against config changes so bad values fail before merge
Document the valid range next to the config key in your repo's config comments

When it happens

Trigger: Setting imaging.jpeg.quality outside 1–100 in site config, or a negative global imaging.quality inherited into the JPEG config (note: 0 means unset and falls through to defaults, so 0 itself doesn't trigger this).

Common situations: Typos (e.g. 850 for 85); assuming a 0–1 float scale; setting a negative value to mean 'disable'; copy-pasting config across tools with different ranges.

Related errors

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