wezterm/wezterm · error · anyhow::Error

Gradient must either specify both segment_size and segment_s

Error message

Gradient must either specify both segment_size and segment_smoothness, or neither

What it means

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.

Source

Thrown at config/src/background.rs:486

                g.html_colors(&colors);
                g.mode(match self.blend {
                    BlendMode::Rgb => CGMode::Rgb,
                    BlendMode::LinearRgb => CGMode::LinearRgb,
                    BlendMode::Hsv => CGMode::Hsv,
                    BlendMode::Oklab => CGMode::Oklab,
                });
                g.interpolation(match self.interpolation {
                    Interpolation::Linear => CGInterp::Linear,
                    Interpolation::Basis => CGInterp::Basis,
                    Interpolation::CatmullRom => CGInterp::CatmullRom,
                });
                g.build()?
            }
        };
        match (self.segment_size, self.segment_smoothness) {
            (Some(size), Some(smoothness)) => Ok(g.sharp(size, smoothness)),
            (None, None) => Ok(g),
            _ => anyhow::bail!(
                "Gradient must either specify both segment_size and segment_smoothness, or neither"
            ),
        }
    }
}

View on GitHub (pinned to 9c04f79f86)

Solutions

Add the missing segment_smoothness (or segment_size) so both are present
Remove both keys to keep the default smooth gradient

Example fix

-- before: only one of the pair -> config error
local bg = {
  source = { Gradient = {
    colors = { '#0000ff', '#ff0000' },
    segment_size = 3,
  } },
  width = '100%',
}

-- after: both keys set together
local bg = {
  source = { Gradient = {
    colors = { '#0000ff', '#ff0000' },
    segment_size = 3,
    segment_smoothness = 0.0,
  } },
  width = '100%',
}

Defensive patterns

Strategy: validation

Validate before calling

-- in wezterm.lua, before returning config
local function assert_gradient(g)
  if (g.segment_size == nil) ~= (g.segment_smoothness == nil) then
    error('Gradient: segment_size and segment_smoothness must be set together')
  end
end

for _, bg in ipairs(backgrounds) do
  if bg.source and bg.source.Gradient then assert_gradient(bg.source.Gradient) end
end

Try / catch

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.

Prevention

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

When it happens

Trigger: wezterm.lua with background = { source = { Gradient = { ... segment_size = 3 } } } but no segment_smoothness, or the mirror case with only segment_smoothness set.

Common situations: 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.

Related errors

AI-assisted analysis of wezterm/wezterm@9c04f79f86 (2026-08-16). Data as JSON: /api/errors/5a7ceab81f060ad0. Report an issue: GitHub.