wezterm/wezterm · error · anyhow::Error

{unsup:?} is not implemented for background color. Use e.g.

Error message

{unsup:?} is not implemented for background color. Use e.g. `width = '100%'` instead

What it means

wezterm throws this when a background layer whose source is a solid Color uses a CSS-style size keyword ('Contain' or 'Cover') for its width. The BackgroundSize enum accepts Contain/Cover/Dimension, but the Color rendering path (which fills an image::RgbaImage sized in pixels) only knows how to evaluate an absolute Dimension; Contain and Cover have no meaningful implementation for a flat color, so load_background_layer bails. The message tells you to use a percentage or pixel dimension instead.

Source

Thrown at wezterm-gui/src/termwindow/background.rs:302

                // To simplify the math, we compute a perfect circle
                // for the radial gradient, and let the texture sampler
                // perturb it to fill the window
                width = width.min(height);
                height = height.min(width);
            }

            CachedGradient::load(g, width, height)?
        }
        BackgroundSource::Color(color) => {
            // In theory we could just make a 1x1 texture and allow
            // the shader to stretch it, but if we do that, it'll blend
            // around the edges and look weird.
            // So we make a square texture in the ballpark of the window
            // surface.
            // It's not ideal.
            let width = match layer.width {
                BackgroundSize::Dimension(d) => d.evaluate_as_pixels(h_context),
                unsup => anyhow::bail!(
                    "{unsup:?} is not implemented for background color. \
                     Use e.g. `width = '100%'` instead"
                ),
            } as u32;
            let height = match layer.height {
                BackgroundSize::Dimension(d) => d.evaluate_as_pixels(v_context),
                unsup => anyhow::bail!(
                    "{unsup:?} is not implemented for background color. \
                     Use e.g. `height = '100%'` instead"
                ),
            } as u32;

            let size = width.min(height);

            let mut imgbuf = image::RgbaImage::new(size, size);
            let src_pixel = {
                let (r, g, b, a) = color.to_srgb_u8();
                image::Rgba([r, g, b, a])

View on GitHub (pinned to 3ff7522b96)

Solutions

1. Change width (and height) to a dimension such as '100%' or a pixel value like '1280px' in the background layer config
2. If you wanted tiling/stretching behavior, keep source = { Color = ... } with width='100%' and height='100%' — a flat color fills the window anyway
3. If you wanted Contain/Cover behavior, use an image or gradient source where those keywords are implemented (or will fail with the gradient-specific message)

Example fix

-- before
config.window_background_image = {
  source = { Color = '#1a1b26' },
  width = 'Contain',
  height = 'Cover',
}

-- after
config.window_background_image = {
  source = { Color = '#1a1b26' },
  width = '100%',
  height = '100%',
}

-- Lua: validate background layers with a Color source before applying them
local function color_layer_ok(layer)
  if type(layer.source) == 'table' and layer.source.Color then
    local ok_w = type(layer.width) == 'string' and layer.width:match('%%$')
      or type(layer.width) == 'number'
    local ok_h = type(layer.height) == 'string' and layer.height:match('%%$')
      or type(layer.height) == 'number'
    return ok_w and ok_h, 'Color source needs width/height as dimension (e.g. 100% or px), not Contain/Cover'
  end
  return true
end

When it happens

Trigger: Setting config like window_background_image = { source = { Color = '#0f0f0f' }, width = 'Contain' } (or 'Cover'). Also triggered by any BackgroundLayer with source = { Color = ... } where width is left as or explicitly set to BackgroundSize::Contain/Cover. Only the width match arm produces this exact message.

Common situations: Copying a background layer config from an image example (where Contain/Cover are legal) and swapping the file path for a solid color. Mixing gradient/image sizing keywords into the newer solid-color background feature introduced for layered backgrounds.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• {unsup:?} is not implemented for background color. Use e.g.
• invalid keycode {}: {:#}, {:#}
• {}
• cannot register module {} as package.loaded.{} is already se
• cannot register module wezterm.{name} as it is already set t

AI-assisted analysis of wezterm/wezterm@3ff7522b96 (2026-08-20). Data as JSON: /api/errors/78d6fc9697534c25. Report an issue: GitHub.