{"record":{"id":"5a7ceab81f060ad0","repo":"wezterm/wezterm","slug":"gradient-must-either-specify-both-segment-size-and","errorCode":null,"errorMessage":"Gradient must either specify both segment_size and segment_smoothness, or neither","messagePattern":"Gradient must either specify both segment_size and segment_smoothness, or neither","errorType":"validation","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"config/src/background.rs","lineNumber":486,"sourceCode":"                g.html_colors(&colors);\n                g.mode(match self.blend {\n                    BlendMode::Rgb => CGMode::Rgb,\n                    BlendMode::LinearRgb => CGMode::LinearRgb,\n                    BlendMode::Hsv => CGMode::Hsv,\n                    BlendMode::Oklab => CGMode::Oklab,\n                });\n                g.interpolation(match self.interpolation {\n                    Interpolation::Linear => CGInterp::Linear,\n                    Interpolation::Basis => CGInterp::Basis,\n                    Interpolation::CatmullRom => CGInterp::CatmullRom,\n                });\n                g.build()?\n            }\n        };\n        match (self.segment_size, self.segment_smoothness) {\n            (Some(size), Some(smoothness)) => Ok(g.sharp(size, smoothness)),\n            (None, None) => Ok(g),\n            _ => anyhow::bail!(\n                \"Gradient must either specify both segment_size and segment_smoothness, or neither\"\n            ),\n        }\n    }\n}\n","sourceCodeStart":468,"sourceCodeEnd":492,"githubUrl":"https://github.com/wezterm/wezterm/blob/9c04f79f86649f76a8c978ff4b674f60297a6ec9/config/src/background.rs#L468-L492","documentation":"When a Gradient background is built from config, the optional segment_size and segment_smoothness keys must be set together (they are passed as a pair to g.sharp(size, smoothness) to render the gradient as discrete segments) or both omitted. A config specifying exactly one of them fails config evaluation with this message.","triggerScenarios":"wezterm.lua with background = { source = { Gradient = { ... segment_size = 3 } } } but no segment_smoothness, or the mirror case with only segment_smoothness set.","commonSituations":"Copying a gradient example and trimming one option; examples or blog posts that only mention segment_size; tweaking values one at a time while iterating on a config.","solutions":["Add the missing segment_smoothness (or segment_size) so both are present","Remove both keys to keep the default smooth gradient"],"exampleFix":"-- before: only one of the pair -> config error\nlocal bg = {\n  source = { Gradient = {\n    colors = { '#0000ff', '#ff0000' },\n    segment_size = 3,\n  } },\n  width = '100%',\n}\n\n-- after: both keys set together\nlocal bg = {\n  source = { Gradient = {\n    colors = { '#0000ff', '#ff0000' },\n    segment_size = 3,\n    segment_smoothness = 0.0,\n  } },\n  width = '100%',\n}","handlingStrategy":"validation","validationCode":"-- in wezterm.lua, before returning config\nlocal function assert_gradient(g)\n  if (g.segment_size == nil) ~= (g.segment_smoothness == nil) then\n    error('Gradient: segment_size and segment_smoothness must be set together')\n  end\nend\n\nfor _, bg in ipairs(backgrounds) do\n  if bg.source and bg.source.Gradient then assert_gradient(bg.source.Gradient) end\nend","typeGuard":null,"tryCatchPattern":"Config errors surface when wezterm evaluates the file; boot with a known-good override while fixing it: wezterm --config 'background={}' , then read the error overlay / WEZTERM_LOG output that names the offending file and line.","preventionTips":["Treat segment_size and segment_smoothness as one unit: add, change or remove them together","Keep gradient snippets in a single helper function so the pairing rule is enforced in one place","After editing a gradient, run `wezterm show-keys` or open a new window to catch config errors immediately"],"tags":["config","lua","gradient","background","validation"],"backgroundTag":"config-validation-failed","analyzedSha":"9c04f79f86649f76a8c978ff4b674f60297a6ec9","analyzedAt":"2026-08-16T21:23:27.157Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}