{"record":{"id":"ccc60e90aef8e9a5","repo":"gohugoio/hugo","slug":"imaging-avif-encoderspeed-must-be-between-1-and-10","errorCode":null,"errorMessage":"imaging.avif.encoderSpeed must be between 1 and 10, got %d","messagePattern":"imaging\\.avif\\.encoderSpeed must be between 1 and 10, got (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"resources/images/config.go","lineNumber":721,"sourceCode":"\t}\n\tif c.Hint == \"\" {\n\t\tc.Hint = defaultHint\n\t}\n\tif c.Compression == \"\" {\n\t\tc.Compression = defaultCompression\n\t}\n\tif c.Quality == 0 {\n\t\tc.Quality = 60\n\t}\n\n\tc.Hint = strings.ToLower(c.Hint)\n\tc.Compression = strings.ToLower(c.Compression)\n\n\tif c.Hint != \"\" && !hints[c.Hint] {\n\t\treturn fmt.Errorf(\"imaging.avif.hint must be one of picture, photo, drawing, icon, or text, got %q\", c.Hint)\n\t}\n\tif c.EncoderSpeed < 1 || c.EncoderSpeed > 10 {\n\t\treturn fmt.Errorf(\"imaging.avif.encoderSpeed must be between 1 and 10, got %d\", c.EncoderSpeed)\n\t}\n\n\tif c.Compression != \"\" && !compressionMethods[c.Compression] {\n\t\treturn fmt.Errorf(\"imaging.avif.compression must be one of lossy or lossless, got %q\", c.Compression)\n\t}\n\tif c.Quality < 1 || c.Quality > 100 {\n\t\treturn fmt.Errorf(\"imaging.avif.quality must be between 1 and 100 inclusive, got %d\", c.Quality)\n\t}\n\n\treturn nil\n}\n\n// WebpConfig holds WebP-specific encoding configuration.\ntype WebpConfig struct {\n\t// Quality setting (1-100). Falls back to the global imaging.quality if unset.\n\t// Only relevant for lossy encoding.\n\tQuality int\n","sourceCodeStart":703,"sourceCodeEnd":739,"githubUrl":"https://github.com/gohugoio/hugo/blob/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/resources/images/config.go#L703-L739","documentation":"Validates the AVIF encoderSpeed trade-off. Must be between 1 and 10 inclusive. The default is 10 (fastest). Lower values produce smaller files at the cost of much longer build times. Note the valid range starts at 1, not 0 — a value of 0 triggers this error because the zero-value check (quality fallback) does not apply to EncoderSpeed.","triggerScenarios":"Setting imaging.avif.encoderSpeed in hugo.toml to 0, a negative number, or any value above 10. Unlike quality, there is no 0-means-default fallback for encoderSpeed — it defaults to 10 only when unset (via defaultAvifEncoderSpeed at construction, not in init()).","commonSituations":"Setting encoderSpeed to 0 thinking it means 'fastest' or 'default'; setting it to 1 for maximum compression and hitting build timeouts; off-by-one confusion with the 0-indexed webp.method range.","solutions":["Set imaging.avif.encoderSpeed to a value between 1 and 10. Stick with the default 10 unless you have a specific reason.","If you need smaller AVIF files, lower the value gradually (try 8, then 6) and monitor build time — values below 5 are very slow.","If you accidentally set it to 0, change it to 10 (the recommended default) or remove the key."],"exampleFix":"# before (hugo.toml)\n[imaging.avif]\nencoderSpeed = 0\n\n# after\n[imaging.avif]\nencoderSpeed = 10","handlingStrategy":"validation","validationCode":"// Validate AVIF encoder speed (1-10, default 10)\nfunc validateAvifEncoderSpeed(speed int) error {\n    if speed < 1 || speed > 10 {\n        return fmt.Errorf(\"avif encoderSpeed %d out of range [1,10]\", speed)\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["encoderSpeed starts at 1, not 0 — a common off-by-one error.","Keep encoderSpeed at 10 (the default) unless you have measured a specific file-size benefit from lowering it.","Values below 5 can cause CI build timeouts on sites with many images."],"tags":["hugo","imaging","avif","config-validation","performance"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}