kovidgoyal/kitty · warning

Ignoring invalid title bar color: {x}

Error message

Ignoring invalid title bar color: {x}

What it means

kitty logs this when a titlebar_color/scrollbar_color value cannot be parsed as a color and is not one of the special values ('system', 'background'). The offending value is ignored and the color resolves to 0. It is a non-fatal config parse warning.

Source

Thrown at kitty/options/utils.py:1002

def custom_shaders(x: str) -> tuple[str, ...]:
    return tuple(shlex_split(x)) if x else ()


def allow_hyperlinks(x: str) -> int:
    if x == 'ask':
        return 0b11
    return 1 if to_bool(x) else 0


def color_with_special_values(x: str, special_values: dict[str, int], error_msg: str) -> int:
    x = x.strip('"')
    if (ans := special_values.get(x)) is not None:
        return ans & 0xFF
    try:
        return (color_as_int(to_color(x)) << 8) | len(special_values)
    except Exception:
        log_error(error_msg.format(x=x))
    return 0


def titlebar_color(x: str) -> int:
    return color_with_special_values(x, {'system': 0, 'background': 1}, 'Ignoring invalid title bar color: {x}')


def scrollbar_color(x: str) -> int:
    return color_with_special_values(x, {'foreground': 0, 'selection_background': 1}, 'Ignoring invalid scroll bar color: {x}')


def macos_titlebar_color(x: str) -> int:
    x = x.strip('"')
    if x == 'light':
        return -1
    if x == 'dark':
        return -2
    return titlebar_color(x)

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Correct the value to a valid kitty color: named color, #rrggbb, #rgb, rgb:RR/GG/BB, or the special values 'system'/'background'.
2. If you intended the default, use 'system' (title bar) or 'background'.
3. Run kitty from a terminal and check the error log to confirm the option now parses.

Example fix

# before
titlebar_color #ff00zz

# after
titlebar_color #ff0000

from kitten_utils import is_valid_color  # pseudo
def valid_color(x: str) -> bool:
    import re
    x = x.strip('"')
    if x in {'system', 'background'}:
        return True
    return bool(re.fullmatch(r'#[0-9a-fA-F]{3}|#[0-9a-fA-F]{6}|rgb:[0-9a-fA-F/?]{1,4}(/[0-9a-fA-F?]*)*', x)) or x.lower() in NAMED_COLORS

def is_special_or_color(x: str) -> bool:
    return x in {'system','background'} or bool(re.fullmatch(r'#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})', x))

When it happens

Trigger: Setting titlebar_color or scrollbar_color in kitty.conf to a malformed value, e.g. 'titlebar_color #ff00zz' or 'titlebar_color reed' (typo of red), or an unsupported color name.

Common situations: Typos in color names, malformed hex codes (wrong number of digits or invalid characters), copy-pasting colors from another terminal's format that kitty does not accept.

Related errors

• This should be run as kitten broadcast
• No option named: {k}
• No custom kitten named {kitten} found
• Not a number: {x} with error: {e}
• Not a valid unit: {x}. Allowed units are: {default_unit}, {"

AI-assisted analysis of kovidgoyal/kitty@6d5d0c4406 (2026-08-27). Data as JSON: /api/errors/a1011c41d74ced21. Report an issue: GitHub.