kovidgoyal/kitty · error

Failed to load custom tab_bar.py module with error: {e}

Error message

Failed to load custom tab_bar.py module with error: {e}

What it means

kitty found a user tab_bar.py in the config dir but importing/executing it raised an exception (other than FileNotFoundError). The custom tab bar is disabled and the default is used.

Source

Thrown at kitty/tab_bar.py:661

    end = screen.cursor.x
    if end < screen.columns:
        screen.draw(' ')
    return end


@run_once
def load_custom_draw_tab_module() -> dict[str, Any]:
    import runpy
    import traceback

    try:
        return runpy.run_path(os.path.join(config_dir, 'tab_bar.py'))
    except FileNotFoundError:
        return {}
    except Exception as e:
        traceback.print_exc()
        log_error(f'Failed to load custom tab_bar.py module with error: {e}')
        return {}


@run_once
def load_custom_draw_tab() -> DrawTabFunc:
    m = load_custom_draw_tab_module()
    func: DrawTabFunc | None = m.get('draw_tab')
    if func is None:
        return draw_tab_with_fade

    @wraps(func)
    def draw_tab(
        draw_data: DrawData, screen: Screen, tab: TabBarData, before: int, max_tab_length: int, index: int, is_last: bool, extra_data: ExtraData
    ) -> int:
        try:
            return func(draw_data, screen, tab, before, max_tab_length, index, is_last, extra_data)
        except Exception as e:
            log_error(f'Custom draw tab function failed with error: {e}')

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Check the traceback kitty printed for the failing line in tab_bar.py
2. Match your draw_tab signature to the current kitty docs: (draw_data, screen, tab, before, max_tab_length, index, is_last, extra_data)
3. Test locally: python3 -c "import runpy; runpy.run_path('~/.config/kitty/tab_bar.py', run_name='x')"

import runpy
try:
    runpy.run_path(os.path.expanduser('~/.config/kitty/tab_bar.py'), run_name='tab_bar')
except Exception as e:
    print('tab_bar.py broken:', e)

try:
    module = runpy.run_path(tab_bar_path)
except FileNotFoundError:
    module = {}  # no customization, fine
except Exception:
    module = {}  # broken; fall back to default tab bar

When it happens

Trigger: runpy.run_path(config_dir/tab_bar.py) raises — syntax error, NameError at import time, or incompatible imports — in load_custom_draw_tab_module.

Common situations: tab_bar.py written for an older kitty API (draw_tab signature changes), Python typos, or missing helper imports after refactor.

Related errors

• Custom draw tab function failed with error: {e}
• 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

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