kovidgoyal/kitty · error · ParsingOfArgsFailed

The colors configuration file {emph(err.filename)} was not f

Error message

The colors configuration file {emph(err.filename)} was not found.

What it means

set-colors parses the given colors file; if the file path does not exist, FileNotFoundError is wrapped into ParsingOfArgsFailed with the filename highlighted.

Source

Thrown at kitty/rc/set_colors.py:86

        + MATCH_TAB_OPTION.replace('--match -m', '--match-tab -t')
    )
    args = RemoteCommand.Args(
        spec='COLOR_OR_FILE ...',
        json_field='colors',
        special_parse='parse_colors_and_files(args)',
        completion=RemoteCommand.CompletionSpec.from_string('type:file group:"CONF files", ext:conf'),
    )

    def message_to_kitty(self, global_opts: RCOptions, opts: 'CLIOptions', args: ArgsType) -> PayloadType:
        final_colors: dict[str, int | None | str] = {}
        transparent_background_colors: tuple[tuple[Color, float], ...] = ()
        from kitty.colors import parse_colors

        if not opts.reset:
            try:
                fc, transparent_background_colors = parse_colors(args)
            except FileNotFoundError as err:
                raise ParsingOfArgsFailed(f'The colors configuration file {emph(err.filename)} was not found.') from err
            except Exception as err:
                raise ParsingOfArgsFailed(str(err)) from err
            final_colors.update(fc)
        if transparent_background_colors:
            final_colors['transparent_background_colors'] = ' '.join(f'{c.as_sharp}@{f}' for c, f in transparent_background_colors)
        ans = {
            'match_window': opts.match,
            'match_tab': opts.match_tab,
            'all': opts.all or opts.reset,
            'configured': opts.configured or opts.reset,
            'colors': final_colors,
            'reset': opts.reset,
        }
        return ans

    def response_from_kitty(self, boss: Boss, window: Window | None, payload_get: PayloadGetType) -> ResponseType:
        from kitty.colors import patch_colors

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Verify the colors file path exists (os.path.isfile) before calling
2. Use an absolute path to the theme file
3. Ensure the filesystem holding the theme is mounted

Example fix

# before
kitten @set-colors ~/themes/missing.conf
# after
kitten @set-colors $(realpath ~/themes/nord.conf)

import os
assert os.path.isfile(path), f'missing theme file: {path}'

try: ... except ParsingOfArgsFailed as e: report missing theme path from message

When it happens

Trigger: kitten @set-colors /path/to/theme.conf where the path does not exist or is not readable (e.g. NFS/sshfs not mounted).

Common situations: Theme-switching scripts referencing themes by relative path from a different cwd, or paths from another machine over SSH.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• No custom kitten named {kitten} found
• {exe} does not exist
• Could not find the geninclude file: {val}, ignoring
• Could not find included config file: {val}, ignoring
• The PNG image: %s could not be opened with error: %s

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