{"record":{"id":"5b3bdcfd8f69807f","repo":"github/copilot-sdk","slug":"session-fs-session-state-path-is-required","errorCode":null,"errorMessage":"session_fs.session_state_path is required","messagePattern":"session_fs\\.session_state_path is required","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/copilot/client.py","lineNumber":420,"sourceCode":"    \"\"\"\n    callbacks: dict[str, BearerTokenProvider] = {}\n    if provider is not None:\n        singular = provider.get(\"bearer_token_provider\")\n        if singular is not None:\n            callbacks[_DEFAULT_BEARER_TOKEN_PROVIDER_NAME] = singular\n    if providers:\n        for named in providers:\n            callback = named.get(\"bearer_token_provider\")\n            if callback is not None:\n                callbacks[named[\"name\"]] = callback\n    return callbacks\n\n\ndef _validate_session_fs_config(config: SessionFsConfig) -> None:\n    if not config.get(\"initial_working_directory\"):\n        raise ValueError(\"session_fs.initial_working_directory is required\")\n    if not config.get(\"session_state_path\"):\n        raise ValueError(\"session_fs.session_state_path is required\")\n    if config.get(\"conventions\") not in (\"posix\", \"windows\"):\n        raise ValueError(\"session_fs.conventions must be either 'posix' or 'windows'\")\n\n\ndef _mcp_servers_to_wire(\n    servers: dict[str, Any],\n) -> dict[str, Any]:\n    \"\"\"Convert MCP server configs from public API format to wire format.\n\n    Renames ``working_directory`` key to ``cwd`` in each server config dict.\n    \"\"\"\n    wire: dict[str, Any] = {}\n    for name, config in servers.items():\n        if \"working_directory\" in config:\n            config = {**config, \"cwd\": config[\"working_directory\"]}\n            del config[\"working_directory\"]\n        wire[name] = config\n    return wire","sourceCodeStart":402,"sourceCodeEnd":438,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/python/copilot/client.py#L402-L438","documentation":"_validate_session_fs_config requires session_fs.session_state_path to be set (truthy): the path where per-session state is persisted. Without it the session filesystem cannot maintain state across calls, so construction of the client fails.","triggerScenarios":"Constructing CopilotClient with a session_fs dict containing initial_working_directory (and valid conventions) but no session_state_path, or with it set to an empty string/None.","commonSituations":"Developers copy a minimal session_fs example and add only the working directory; config templating drops the state path because it looks optional; the state path is expected to default relative to the working directory but does not.","solutions":["Set session_fs['session_state_path'] to a writable file path for session state","Verify the value is non-empty and that the parent directory exists and is writable","Derive it explicitly, e.g. os.path.join(base, 'session_state.json'), rather than relying on a default","Pre-validate the session_fs dict (all three keys) before constructing CopilotClient"],"exampleFix":"// before\nclient = CopilotClient(session_fs={\"initial_working_directory\": \"/workspace\", \"conventions\": \"posix\"})\n\n// after\nclient = CopilotClient(session_fs={\n    \"initial_working_directory\": \"/workspace\",\n    \"session_state_path\": \"/workspace/.copilot/session_state.json\",\n    \"conventions\": \"posix\",\n})","handlingStrategy":"validation","validationCode":"def check_session_fs(config: dict) -> None:\n    if not config.get(\"session_state_path\"):\n        raise ValueError(\"session_fs.session_state_path is required\")","typeGuard":"def session_fs_is_complete(config: dict) -> bool:\n    return bool(config.get(\"initial_working_directory\")) and bool(config.get(\"session_state_path\")) and config.get(\"conventions\") in (\"posix\", \"windows\")","tryCatchPattern":"try:\n    client = CopilotClient(session_fs=cfg)\nexcept ValueError as e:\n    if \"session_state_path is required\" in str(e):\n        cfg = {**cfg, \"session_state_path\": os.path.join(cfg[\"initial_working_directory\"], \"session_state.json\")}\n        client = CopilotClient(session_fs=cfg)","preventionTips":["Always set session_state_path explicitly — it does not default relative to the working directory","Derive the state path from base_directory with os.path.join so it is never omitted","Verify the parent directory of session_state_path exists and is writable before constructing the client","Validate all three session_fs keys together in one pre-construction check"],"tags":["configuration","python","session-fs","validation"],"backgroundTag":"missing-required-config-field","analyzedSha":"cd8cf15dc3f9e762615790aaed0a771a0f392755","analyzedAt":"2026-09-09T18:32:31.973Z","contentChangedAt":"2026-09-09T18:32:31.973Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}