{"record":{"id":"78d6fc9697534c25","repo":"wezterm/wezterm","slug":"unsup-is-not-implemented-for-background-color","errorCode":null,"errorMessage":"{unsup:?} is not implemented for background color. Use e.g. `width = '100%'` instead","messagePattern":"(.+?) is not implemented for background color\\. Use e\\.g\\. `width = '100%'` instead","errorType":"validation","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"wezterm-gui/src/termwindow/background.rs","lineNumber":302,"sourceCode":"                // To simplify the math, we compute a perfect circle\n                // for the radial gradient, and let the texture sampler\n                // perturb it to fill the window\n                width = width.min(height);\n                height = height.min(width);\n            }\n\n            CachedGradient::load(g, width, height)?\n        }\n        BackgroundSource::Color(color) => {\n            // In theory we could just make a 1x1 texture and allow\n            // the shader to stretch it, but if we do that, it'll blend\n            // around the edges and look weird.\n            // So we make a square texture in the ballpark of the window\n            // surface.\n            // It's not ideal.\n            let width = match layer.width {\n                BackgroundSize::Dimension(d) => d.evaluate_as_pixels(h_context),\n                unsup => anyhow::bail!(\n                    \"{unsup:?} is not implemented for background color. \\\n                     Use e.g. `width = '100%'` instead\"\n                ),\n            } as u32;\n            let height = match layer.height {\n                BackgroundSize::Dimension(d) => d.evaluate_as_pixels(v_context),\n                unsup => anyhow::bail!(\n                    \"{unsup:?} is not implemented for background color. \\\n                     Use e.g. `height = '100%'` instead\"\n                ),\n            } as u32;\n\n            let size = width.min(height);\n\n            let mut imgbuf = image::RgbaImage::new(size, size);\n            let src_pixel = {\n                let (r, g, b, a) = color.to_srgb_u8();\n                image::Rgba([r, g, b, a])","sourceCodeStart":284,"sourceCodeEnd":320,"githubUrl":"https://github.com/wezterm/wezterm/blob/3ff7522b9617ec920f7fbdb22b57e93d42d93ee9/wezterm-gui/src/termwindow/background.rs#L284-L320","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Change width (and height) to a dimension such as '100%' or a pixel value like '1280px' in the background layer config","If you wanted tiling/stretching behavior, keep source = { Color = ... } with width='100%' and height='100%' — a flat color fills the window anyway","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)"],"exampleFix":"-- before\nconfig.window_background_image = {\n  source = { Color = '#1a1b26' },\n  width = 'Contain',\n  height = 'Cover',\n}\n\n-- after\nconfig.window_background_image = {\n  source = { Color = '#1a1b26' },\n  width = '100%',\n  height = '100%',\n}","handlingStrategy":"validation","validationCode":"-- Lua: validate background layers with a Color source before applying them\nlocal function color_layer_ok(layer)\n  if type(layer.source) == 'table' and layer.source.Color then\n    local ok_w = type(layer.width) == 'string' and layer.width:match('%%$')\n      or type(layer.width) == 'number'\n    local ok_h = type(layer.height) == 'string' and layer.height:match('%%$')\n      or type(layer.height) == 'number'\n    return ok_w and ok_h, 'Color source needs width/height as dimension (e.g. 100% or px), not Contain/Cover'\n  end\n  return true\nend","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only use 'Contain'/'Cover' with image/gradient sources; always give Color sources explicit '100%' or pixel dimensions","Keep background layer config in one table so invalid combos are caught by a single helper before assignment"],"tags":["wezterm","config","background","lua"],"backgroundTag":"invalid-config-value","analyzedSha":"3ff7522b9617ec920f7fbdb22b57e93d42d93ee9","analyzedAt":"2026-08-20T04:47:31.434Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}