imaging.jpeg.quality must be between 1 and 100 inclusive…

Error message

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

What it means

Validates the JPEG-specific quality after fallback resolution. If imaging.jpeg.quality is 0, it inherits the global imaging.quality; if that is also 0, it defaults to 75. After resolution, quality must be between 1 and 100 inclusive. This check runs inside JpegConfig.init, which is called from ImagingConfig.init.

Solutions

Set imaging.jpeg.quality to a value between 1 and 100 in hugo.toml (typical web values: 70-85).
If you want the default (75), simply omit the quality key under [imaging.jpeg].
If you set it to 0 intentionally to inherit the global quality, make sure the global imaging.quality is itself valid (1-100).

Example fix

# before (hugo.toml)
[imaging.jpeg]
quality = 0

[imaging]
quality = 0
# jpeg quality resolves to default 75 — fine, but if you explicitly want control:

# after
[imaging.jpeg]
quality = 82

Defensive patterns

Strategy: validation

Validate before calling

// Validate JPEG quality (0 = inherit global or default 75)
func validateJpegQuality(q, globalQuality int) error {
    resolved := q
    if resolved == 0 { resolved = globalQuality }
    if resolved == 0 { resolved = 75 }
    if resolved < 1 || resolved > 100 {
        return fmt.Errorf("jpeg quality resolves to %d, out of range [1,100]", resolved)
    }
    return nil
}

Prevention

Omit imaging.jpeg.quality to inherit the global imaging.quality or default 75.
For web JPEGs, 70-85 is the sweet spot; above 90 yields minimal visible improvement with large files.
JPEG does not support lossless in Hugo — use WebP or AVIF with compression='lossless' instead.

When it happens

Trigger: Setting [imaging.jpeg] quality in hugo.toml to a value below 1 or above 100. Note: a quality of 0 does NOT trigger this error — it triggers the fallback chain to the global quality or default 75.

Common situations: Setting JPEG quality to 0 expecting lossless encoding (JPEG does not support lossless in Hugo); setting quality above 100; an off-by-one from a config migration.

Related errors

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

Appendix: 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 52c9bd7908)