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

Error message

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

What it means

Validates the global imaging.quality field. The code checks cfg.Quality < 0 || cfg.Quality > 100, so a value of 0 is allowed (meaning 'unset — use per-format defaults'). Any negative value or value above 100 is rejected. The message text says 'between 1 and 100' because 0 is the sentinel for 'not configured' rather than a meaningful quality.

Solutions

Set imaging.quality to a value between 1 and 100 in hugo.toml, or omit it entirely to use per-format defaults (JPEG 75, WebP 75, AVIF 60).
If you want maximum quality, use 100 — not a value above it.
Verify there are no stray characters or encoding issues in the TOML/YAML value.

Example fix

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

# after
[imaging]
quality = 100

Defensive patterns

Strategy: validation

Validate before calling

// Validate global imaging quality
func validateGlobalQuality(q int) error {
    // 0 is allowed (means 'use per-format defaults'); 1-100 is explicit.
    if q < 0 || q > 100 {
        return fmt.Errorf("imaging.quality must be 0 or 1-100, got %d", q)
    }
    return nil
}

Prevention

Omit imaging.quality entirely if you want per-format defaults — JPEG 75, WebP 75, AVIF 60.
Never set quality above 100; the maximum meaningful value is 100.
Remember that quality 0 is not an error here — it means 'unset'.

When it happens

Trigger: Setting imaging.quality in hugo.toml to a negative number or a value above 100. The zero value (Go int default) does NOT trigger this error because 0 means 'inherit per-format defaults.'

Common situations: Setting quality to 100+ thinking higher is always better; a YAML/TOML parser interpreting a quoted "100" plus a stray digit; importing a config from a tool that uses 0-1000 quality scales.

Related errors

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

Appendix: source

Thrown at resources/images/config.go:577

}

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"
	}

	if len(cfg.Meta.Fields) == 0 {
		// Default: include all fields except technical metadata.
		// Don't change this for no good reason. Please don't.
		cfg.Meta.Fields = []string{
			"! *{GPS,Exif,Exposure[MPB],Contrast,Resolution,Sharp,JPEG,Metering,Sensing,Saturation,ColorSpace,Flash,WhiteBalance}*",
		}
	}

View on GitHub (pinned to 52c9bd7908)