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

Error message

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

What it means

During site-config initialization, ImagingConfig.init validates the global imaging.quality setting. Values outside 0–100 fail (0 is allowed here as 'unset' and later defaulted per-format), because encoders require quality in 1–100.

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

Solutions

Set imaging.quality in hugo.toml to a value between 1 and 100 (Hugo's default is 75).
Remove the setting entirely to use the default.
If different formats need different quality, use imaging.jpeg.quality / per-call q options instead of an out-of-range global.

Example fix

# before (hugo.toml)
[imaging]
quality = 150
# after
[imaging]
quality = 75

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

Validate site config (hugo.toml [imaging] quality) before deploys, e.g. in CI with a dry-run build
Remember quality defaults to 75; only set it when needed and keep it in 1–100
Treat config validation failures as fail-fast build errors, not warnings

When it happens

Trigger: Setting imaging.quality = 150, -1, or any value > 100 or < 0 in hugo.toml/config.toml (or the params equivalent) — the error fires at config load, before any image is processed.

Common situations: Confusing quality percentages with other scales (e.g. entering 0–1 floats multiplied wrong, or 0–255); typos like 750 for 75; copying config from tools with different quality ranges.

Related errors

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