{"record":{"id":"39fb45b631455179","repo":"github/copilot-sdk","slug":"session-fs-initial-working-directory-is-required","errorCode":null,"errorMessage":"session_fs.initial_working_directory is required","messagePattern":"session_fs\\.initial_working_directory is required","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/copilot/client.py","lineNumber":418,"sourceCode":"    ``hasBearerTokenProvider: true`` instead and the runtime calls back over\n    ``providerToken.getToken``.\n    \"\"\"\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\"]","sourceCodeStart":400,"sourceCodeEnd":436,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/python/copilot/client.py#L400-L436","documentation":"_validate_session_fs_config requires session_fs.initial_working_directory to be set (truthy) when a session_fs config is provided. The session-filesystem feature needs a starting directory for every session and refuses a config that omits it.","triggerScenarios":"Constructing CopilotClient with session_fs={...} that lacks initial_working_directory, or passes an empty string/None for it; validation runs in __init__ before any session is created.","commonSituations":"Config dicts built dynamically where the key is only set when an env var exists; YAML/JSON config missing the field; renaming the key (e.g. from 'workdir') so the expected key is absent.","solutions":["Set session_fs['initial_working_directory'] to an absolute path that exists","Ensure the value is non-empty (empty string is treated as missing)","Load the value from a verified env var/config key and assert it before constructing the client","Validate the whole session_fs dict with a schema check before passing it to CopilotClient"],"exampleFix":"// before\nclient = CopilotClient(session_fs={\"session_state_path\": \"/tmp/state.json\", \"conventions\": \"posix\"})\n\n// after\nclient = CopilotClient(session_fs={\n    \"initial_working_directory\": \"/workspace\",\n    \"session_state_path\": \"/tmp/state.json\",\n    \"conventions\": \"posix\",\n})","handlingStrategy":"validation","validationCode":"def check_session_fs(config: dict) -> None:\n    if not config.get(\"initial_working_directory\"):\n        raise ValueError(\"session_fs.initial_working_directory 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 \"initial_working_directory is required\" in str(e):\n        cfg = {**cfg, \"initial_working_directory\": os.environ[\"WORKSPACE_DIR\"]}\n        client = CopilotClient(session_fs=cfg)","preventionTips":["Use a dataclass/TypedDict for SessionFsConfig so missing keys fail type checks","Validate the session_fs dict against a schema at config load time","Ensure env-var-backed values are non-empty before building the config","Set initial_working_directory to an absolute path that exists on the target machine"],"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"}