{"record":{"id":"f413970e9052ec0e","repo":"kovidgoyal/kitty","slug":"unknown-command-in-session-file-cmd","errorCode":null,"errorMessage":"Unknown command in session file: {cmd}","messagePattern":"Unknown command in session file: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"kitty/session.py","lineNumber":297,"sourceCode":"            elif cmd == 'os_window_size':\n                w, h = map(window_size, rest.split(maxsplit=1))\n                ans.os_window_size = WindowSizes(WindowSize(*w), WindowSize(*h))\n            elif cmd == 'os_window_class':\n                ans.os_window_class = rest\n            elif cmd == 'os_window_name':\n                ans.os_window_name = rest\n            elif cmd == 'os_window_title':\n                ans.os_window_title = rest\n            elif cmd == 'os_window_state':\n                ans.os_window_state = rest\n            elif cmd == 'resize_window':\n                ans.resize_window(rest.split())\n            elif cmd == 'focus_matching_window':\n                ans.focus_matching_window(rest)\n            elif cmd == 'set_layout_state':\n                ans.set_layout_state(rest)\n            else:\n                raise ValueError(f'Unknown command in session file: {cmd}')\n    yield finalize_session(ans)\n\n\nclass PreReadSession(str):\n    associated_environ: Mapping[str, str]\n    session_arg: str\n    session_path: str\n\n    def __new__(cls, val: str, associated_environ: Mapping[str, str], session_arg: str, session_path: str) -> 'PreReadSession':\n        ans: PreReadSession = str.__new__(cls, val)\n        ans.associated_environ = associated_environ\n        ans.session_arg = session_arg\n        ans.session_path = session_path\n        return ans\n\n\ndef create_sessions(\n    opts: Options,","sourceCodeStart":279,"sourceCodeEnd":315,"githubUrl":"https://github.com/kovidgoyal/kitty/blob/6d5d0c440603ad9bdf6dcd599f73f6dde21acb44/kitty/session.py#L279-L315","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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","Upgrade kitty if the command is valid in newer versions","Check spelling of the command keyword against kitty's session docs / parse_session source","Prefix genuine comments with '#'"],"exampleFix":"# before (session file)\nmap ctrl+c copy_to_clipboard\nlaunch sh\n# after\nlaunch sh","handlingStrategy":"validation","validationCode":"KNOWN = {'env', 'launch', 'layout', 'cd', 'focus', 'focus_matching_window', 'resize_window', 'set_layout_state', 'new_tab', 'new_os_window'}\n\ndef session_lines_ok(text: str) -> list[str]:\n    return [l for l in text.splitlines() if not l.strip() or l.lstrip().startswith('#') or l.split(maxsplit=1)[0] in KNOWN]","typeGuard":null,"tryCatchPattern":"try:\n    sessions = list(parse_session(...))\nexcept ValueError as e:\n    if 'Unknown command' in str(e):\n        line = str(e).split(':')[-1].strip()\n        raise ConfigError(f'Unsupported session directive: {line}') from e\n    raise","preventionTips":["Keep kitty.conf directives out of session files","Check session command names against your kitty version's docs","Comment session files with '#' only"],"tags":["kitty","session","unknown-command","config-validation"],"backgroundTag":"unknown-config-directive","analyzedSha":"6d5d0c440603ad9bdf6dcd599f73f6dde21acb44","analyzedAt":"2026-08-27T14:20:20.142Z","schemaVersion":2},"datasetVersion":"2026-08-27T19:17:21.184Z"}