Hmbown/CodeWhale · error · anyhow::Error

Failed to update setting: invalid background_color '{value}'

Error message

Failed to update setting: invalid background_color '{value}'. Expected #RRGGBB, RRGGBB, or default.

What it means

The TUI settings updater normalizes the 'background_color' setting via normalize_background_color_setting. An empty value or one of the aliases 'default'/'none'/'reset'/'off' (case-insensitive) is accepted and mapped to None (theme default). Any other value must parse as a 6-digit ASCII hex RGB color (optional leading '#') through normalize_hex_rgb_color; parse_hex_rgb_color rejects anything that is not exactly 6 hex digits. When parsing fails, this error is returned, echoing the offending value.

Source

Thrown at crates/tui/src/settings.rs:2759

}

fn normalize_optional_background_color(value: Option<&str>) -> Option<String> {
    value.and_then(|raw| normalize_background_color_setting(raw).ok().flatten())
}

fn normalize_background_color_setting(value: &str) -> Result<Option<String>> {
    let trimmed = value.trim();
    if trimmed.is_empty()
        || matches!(
            trimmed.to_ascii_lowercase().as_str(),
            "default" | "none" | "reset" | "off"
        )
    {
        return Ok(None);
    }

    normalize_hex_rgb_color(trimmed).map(Some).ok_or_else(|| {
        anyhow::anyhow!(
            "Failed to update setting: invalid background_color '{value}'. Expected #RRGGBB, RRGGBB, or default."
        )
    })
}

fn normalize_sidebar_focus(value: &str) -> &str {
    match value.trim().to_ascii_lowercase().as_str() {
        "pinned" | "visible" | "show" | "on" | "work" | "plan" | "todos" => "pinned",
        "tasks" | "activity" | "live" | "running" => "tasks",
        "agents" | "subagents" | "sub-agents" => "agents",
        "context" => "context",
        "sessions" | "sessions_rail" | "session_history" => "sessions",
        "hidden" | "hide" | "closed" | "off" | "none" => "hidden",
        _ => "auto",
    }
}

fn is_false(value: &bool) -> bool {

View on GitHub (pinned to 0c42157ee5)

Solutions

1. Use a 6-digit hex color with or without '#': '#1e1e2e' or '1e1e2e'.
2. To reset to the theme default, pass 'default' (or empty string, 'none', 'reset', 'off').
3. Check for stray characters: exactly 6 hex digits survive — '#fff', '#ffffff00', 'rgb(0,0,0)' are all rejected.
4. If a named color is wanted, convert it to hex first (e.g. 'blue' -> '#0000ff').

Example fix

// before
set_setting("background_color", "blue")
set_setting("background_color", "#fff")

// after
set_setting("background_color", "#0000ff")
set_setting("background_color", "default")

fn is_valid_background_color(v: &str) -> bool {
    let t = v.trim();
    t.is_empty()
        || matches!(t.to_ascii_lowercase().as_str(), "default" | "none" | "reset" | "off")
        || {
            let hex = t.strip_prefix('#').unwrap_or(t);
            hex.len() == 6 && hex.chars().all(|c| c.is_ascii_hexdigit())
        }
}

if !is_valid_background_color(value) {
    return Err(format!("invalid background_color '{value}': use #RRGGBB, RRGGBB, or default"));
}
set_setting("background_color", value)?;

function isHexRgbColor(value: string): boolean {
  const t = value.trim();
  const hex = t.startsWith('#') ? t.slice(1) : t;
  return /^[0-9a-fA-F]{6}$/.test(hex);
}

When it happens

Trigger: Calling the settings-update API with background_color set to a named CSS color ('blue'), a 3-digit hex ('#fff'), rgb()/hsl() notation, a 7-digit hex, or any non-hex string. The value is trimmed and lowercased only for the alias check, so 'DEFAULT' works but 'transparent' does not.

Common situations: A model or config file copies colors from a CSS theme (named colors, #RGB shorthand), typos a 5- or 7-digit hex, or passes 'auto'/'transparent' expecting it to mean default.

Related errors

• Failed to update setting: invalid ocean treatment '{value}'.
• Failed to update setting: invalid focus texture '{value}'. E
• Failed to update setting: invalid work surface placement '{v
• Failed to parse boolean '{value}': expected on/off, true/fal
• Invalid {key} '{value}': expected {min}-{max}

AI-assisted analysis of Hmbown/CodeWhale@0c42157ee5 (2026-08-20). Data as JSON: /api/errors/8c67bc467c1f577d. Report an issue: GitHub.