kovidgoyal/kitty · warning

Invalid tab title template: "{template}" with error: {e}

Error message

Invalid tab title template: "{template}" with error: {e}

What it means

A tab title template (tab_title_template / active_tab_title_template) failed to compile as a Python f-string expression. kitty logs the invalid template once (lru_cache dedupes) and falls back to a plain title.

Source

Thrown at kitty/tab_bar.py:138

    LEFT_EDGE: 'left',
    TOP_EDGE: 'top',
    RIGHT_EDGE: 'right',
    BOTTOM_EDGE: 'bottom',
}


def normalized_tab_bar_align(align: str) -> Literal['start', 'end', 'center']:
    match align:
        case 'left' | 'start':
            return 'start'
        case 'right' | 'end':
            return 'end'
    return 'center'


@lru_cache
def report_template_failure(template: str, e: str) -> None:
    log_error(f'Invalid tab title template: "{template}" with error: {e}')


@lru_cache
def compile_template(template: str) -> Any:
    try:
        return compile('f"""' + template + '"""', '<template>', 'eval')
    except Exception as e:
        report_template_failure(template, str(e))


class ColorFormatter:
    draw_data: DrawData
    tab_data: TabBarData

    def __init__(self, which: str):
        self.which = which

    def __getattr__(self, name: str) -> str:

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Validate the template as an f-string expression: python3 -c 'compile(f"""<template>""", "<t>", "eval")'
2. Use only documented variables (fmt, index, layout_name, num_windows, title) and fmt.date()
3. Fix unmatched braces — literal braces must be doubled {{ }}

Example fix

# before
tab_title_template "{index+1}: {title"

# after
tab_title_template "{index+1}: {title}"

def template_ok(t: str) -> bool:
    try:
        compile('f"""' + t + '"""', '<template>', 'eval')
        return True
    except SyntaxError:
        return False
# validate before setting
template_ok('{index+1}: {title}') or fail()

def is_valid_template(t: str) -> bool:
    try:
        compile('f"""' + t + '"""', '<t>', 'eval')
        return True
    except SyntaxError:
        return False

When it happens

Trigger: compile('f"""'+template+'"""') raises SyntaxError, reported via report_template_failure from compile_template/apply_title_template.

Common situations: Templates using unsupported syntax: {index+} style placeholders with typos, unmatched braces, or trying to call functions not in the template namespace (fmt, index, layout_name...).

Related errors

• The value {val} is not a valid choice for tab_bar_align
• The value {val} is not a valid choice for tab_bar_style
• The value {val} is not a valid choice for tab_powerline_styl
• Invalid tab_bar_margin_height: {x}, ignoring
• This should be run as kitten broadcast

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