github/copilot-sdk · error · ValueError

session_fs.initial_working_directory is required

Error message

session_fs.initial_working_directory is required

What it means

_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.

Solutions

1. Set session_fs['initial_working_directory'] to an absolute path that exists
2. Ensure the value is non-empty (empty string is treated as missing)
3. Load the value from a verified env var/config key and assert it before constructing the client
4. Validate the whole session_fs dict with a schema check before passing it to CopilotClient

Example fix

// before
client = CopilotClient(session_fs={"session_state_path": "/tmp/state.json", "conventions": "posix"})

// after
client = CopilotClient(session_fs={
    "initial_working_directory": "/workspace",
    "session_state_path": "/tmp/state.json",
    "conventions": "posix",
})

def check_session_fs(config: dict) -> None:
    if not config.get("initial_working_directory"):
        raise ValueError("session_fs.initial_working_directory is required")

def session_fs_is_complete(config: dict) -> bool:
    return bool(config.get("initial_working_directory")) and bool(config.get("session_state_path")) and config.get("conventions") in ("posix", "windows")

try:
    client = CopilotClient(session_fs=cfg)
except ValueError as e:
    if "initial_working_directory is required" in str(e):
        cfg = {**cfg, "initial_working_directory": os.environ["WORKSPACE_DIR"]}
        client = CopilotClient(session_fs=cfg)

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• session_fs.session_state_path is required
• Invalid value ' '. Expected 'inprocess', 'stdio', or unset.
• gitHubToken and useLoggedInUser cannot be used with…
• sessionFs.initialCwd is required
• sessionFs.sessionStatePath is required

AI-assisted analysis of github/copilot-sdk@cd8cf15dc3 (2026-09-09). Data as JSON: /api/errors/39fb45b631455179. Report an issue: GitHub.

Appendix: source

Thrown at python/copilot/client.py:418

    ``hasBearerTokenProvider: true`` instead and the runtime calls back over
    ``providerToken.getToken``.
    """
    callbacks: dict[str, BearerTokenProvider] = {}
    if provider is not None:
        singular = provider.get("bearer_token_provider")
        if singular is not None:
            callbacks[_DEFAULT_BEARER_TOKEN_PROVIDER_NAME] = singular
    if providers:
        for named in providers:
            callback = named.get("bearer_token_provider")
            if callback is not None:
                callbacks[named["name"]] = callback
    return callbacks


def _validate_session_fs_config(config: SessionFsConfig) -> None:
    if not config.get("initial_working_directory"):
        raise ValueError("session_fs.initial_working_directory is required")
    if not config.get("session_state_path"):
        raise ValueError("session_fs.session_state_path is required")
    if config.get("conventions") not in ("posix", "windows"):
        raise ValueError("session_fs.conventions must be either 'posix' or 'windows'")


def _mcp_servers_to_wire(
    servers: dict[str, Any],
) -> dict[str, Any]:
    """Convert MCP server configs from public API format to wire format.

    Renames ``working_directory`` key to ``cwd`` in each server config dict.
    """
    wire: dict[str, Any] = {}
    for name, config in servers.items():
        if "working_directory" in config:
            config = {**config, "cwd": config["working_directory"]}
            del config["working_directory"]

View on GitHub (pinned to cd8cf15dc3)