kovidgoyal/kitty · error

Failed to load custom tab_bar.py module with error

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.

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
• Failed to load cmd check function from
• Invalid tab_bar_margin_height
• Invalid tab title template
• The value is not a valid choice for tab_bar_align

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

Appendix: 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)