kovidgoyal/kitty · error · ValueError

Unknown command in session file: {cmd}

Error message

Unknown command in session file: {cmd}

What it means

Raised by parse_session when a line in a session file starts with a command keyword that kitty's session parser does not recognize. Every directive must match the supported command set (env, launch, layout, etc.); anything else aborts parsing with this ValueError.

Source

Thrown at kitty/session.py:297

            elif cmd == 'os_window_size':
                w, h = map(window_size, rest.split(maxsplit=1))
                ans.os_window_size = WindowSizes(WindowSize(*w), WindowSize(*h))
            elif cmd == 'os_window_class':
                ans.os_window_class = rest
            elif cmd == 'os_window_name':
                ans.os_window_name = rest
            elif cmd == 'os_window_title':
                ans.os_window_title = rest
            elif cmd == 'os_window_state':
                ans.os_window_state = rest
            elif cmd == 'resize_window':
                ans.resize_window(rest.split())
            elif cmd == 'focus_matching_window':
                ans.focus_matching_window(rest)
            elif cmd == 'set_layout_state':
                ans.set_layout_state(rest)
            else:
                raise ValueError(f'Unknown command in session file: {cmd}')
    yield finalize_session(ans)


class PreReadSession(str):
    associated_environ: Mapping[str, str]
    session_arg: str
    session_path: str

    def __new__(cls, val: str, associated_environ: Mapping[str, str], session_arg: str, session_path: str) -> 'PreReadSession':
        ans: PreReadSession = str.__new__(cls, val)
        ans.associated_environ = associated_environ
        ans.session_arg = session_arg
        ans.session_path = session_path
        return ans


def create_sessions(
    opts: Options,

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Remove or move kitty.conf-only directives out of the session file; only session commands (env, launch, layout, cd, focus, resize_window, etc.) are allowed
2. Upgrade kitty if the command is valid in newer versions
3. Check spelling of the command keyword against kitty's session docs / parse_session source
4. Prefix genuine comments with '#'

Example fix

# before (session file)
map ctrl+c copy_to_clipboard
launch sh
# after
launch sh

KNOWN = {'env', 'launch', 'layout', 'cd', 'focus', 'focus_matching_window', 'resize_window', 'set_layout_state', 'new_tab', 'new_os_window'}

def session_lines_ok(text: str) -> list[str]:
    return [l for l in text.splitlines() if not l.strip() or l.lstrip().startswith('#') or l.split(maxsplit=1)[0] in KNOWN]

try:
    sessions = list(parse_session(...))
except ValueError as e:
    if 'Unknown command' in str(e):
        line = str(e).split(':')[-1].strip()
        raise ConfigError(f'Unsupported session directive: {line}') from e
    raise

When it happens

Trigger: A session file containing an unsupported directive, e.g. 'map ...', 'font_size 12', comments not starting with '#', a typo like 'launsh ...', or a command introduced in a newer kitty version being used on an older kitty.

Common situations: Copying config snippets from kitty.conf into a session file (they are different formats); version mismatches where newer directives (e.g. 'set_layout_state', 'focus_matching_window') don't exist in older kitty builds.

Related errors

• {val} is not a valid layout
• Unknown action: {action}
• {args[1]} is not a known entry point. Choices are:
• Unknown kitty remote control command: {cmd_name}
• This must be run as kitten ask

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