gohugoio/hugo · error

invalid jpeg config: %w

Error message

invalid jpeg config: %w

What it means

Returned by ImagingConfig.init when JpegConfig.init fails, wrapping the jpeg-specific error. JpegConfig.init validates that imaging.jpeg.quality (falling back to imaging.quality then 75) is between 1 and 100 inclusive. The %w preserves the underlying message ('imaging.jpeg.quality must be between 1 and 100 inclusive, got N').

Source

Thrown at resources/images/config.go:568

		return cfg.Avif.Hint
	}
	return ""
}

var validMetaSources = map[string]bool{
	"exif": true,
	"iptc": true,
	"xmp":  true,
}

func (cfg *ImagingConfig) init() error {
	cfg.BgColor = strings.ToLower(strings.TrimPrefix(cfg.BgColor, "#"))
	cfg.Anchor = strings.ToLower(cfg.Anchor)
	cfg.ResampleFilter = strings.ToLower(cfg.ResampleFilter)
	cfg.Hint = strings.ToLower(cfg.Hint)
	cfg.Compression = strings.ToLower(cfg.Compression)
	if err := cfg.Jpeg.init(cfg); err != nil {
		return fmt.Errorf("invalid jpeg config: %w", err)
	}
	if err := cfg.Webp.init(cfg); err != nil {
		return fmt.Errorf("invalid webp config: %w", err)
	}
	if err := cfg.Avif.init(cfg); err != nil {
		return fmt.Errorf("invalid avif config: %w", err)
	}
	if cfg.Quality < 0 || cfg.Quality > 100 {
		return fmt.Errorf("imaging.quality must be between 1 and 100 inclusive, got %d", cfg.Quality)
	}

	if cfg.Anchor == "" {
		cfg.Anchor = smartCropIdentifier
	}

	if strings.TrimSpace(cfg.Exif.IncludeFields) == "" && strings.TrimSpace(cfg.Exif.ExcludeFields) == "" {
		// Don't change this for no good reason. Please don't.
		cfg.Exif.ExcludeFields = "GPS|Exif|Exposure[M|P|B]|Contrast|Resolution|Sharp|JPEG|Metering|Sensing|Saturation|ColorSpace|Flash|WhiteBalance"

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Set imaging.jpeg.quality to an integer between 1 and 100 inclusive.
2. If using the deprecated imaging.quality, ensure it is in 1-100.
3. Omit quality to accept the default of 75.

Example fix

// before
[imaging.jpeg]
quality = 0

// after
[imaging.jpeg]
quality = 75

func validJpegQuality(q int) bool { return q >= 1 && q <= 100 }

func isValidJpegQuality(q int) bool { return q >= 1 && q <= 100 }

if err := cfg.Imaging.init(); err != nil {
    if strings.Contains(err.Error(), "invalid jpeg config") { /* fix imaging.jpeg.quality */ }
}

When it happens

Trigger: Setting [imaging.jpeg] quality = 0 or quality = 150 (out of 1-100) in hugo.toml, or imaging.quality = 200 which propagates as the jpeg fallback. Fails at startup during config decode.

Common situations: A quality value of 0 (mistakenly thinking 0 means default), a value greater than 100, or a negative value; misreading the 1-100 inclusive range.

Related errors

• invalid color code: %q
• invalid anchor value %q in imaging config
• %q is not a valid resample filter
• role name cannot be empty
• version name cannot be empty

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