github/copilot-sdk · error · ValueError

session_fs.conventions must be either 'posix' or 'windows'

Error message

session_fs.conventions must be either 'posix' or 'windows'

What it means

This ValueError is raised by _validate_session_fs_config when the SessionFsConfig passed to CopilotClient has a 'conventions' key that is not exactly 'posix' or 'windows'. The library uses this field to pick path-handling rules for the session filesystem, so an unknown value cannot be safely interpreted and construction is aborted in __init__.

Solutions

1. Set session_fs.conventions to exactly 'posix' or 'windows' (lowercase)
2. If deriving the value from the OS, map it explicitly: {'nt': 'windows'}.get(os.name, 'posix')
3. Check the config file/env source for typos or surrounding whitespace and strip/normalize the string

Example fix

// before
config = {"session_fs": {"initial_working_directory": "/tmp", "session_state_path": "/tmp/s", "conventions": os.name}}
// after
conventions = "windows" if os.name == "nt" else "posix"
config = {"session_fs": {"initial_working_directory": "/tmp", "session_state_path": "/tmp/s", "conventions": conventions}}

cfg = opts.get("session_fs", {})
if cfg.get("conventions") not in ("posix", "windows"):
    raise ValueError(f"conventions must be 'posix' or 'windows', got {cfg.get('conventions')!r}")
if not cfg.get("initial_working_directory") or not cfg.get("session_state_path"):
    raise ValueError("session_fs requires initial_working_directory and session_state_path")

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

When it happens

Trigger: Constructing CopilotClient with a session_fs config whose 'conventions' is misspelled (e.g. 'POSIX', 'Unix', 'win32', 'nt'), None, omitted casing variants, or loaded from a YAML/JSON config file with an unexpected string.

Common situations: Hand-editing a config file with OS-specific naming habits ('win32', 'nt'), building the dict programmatically from an env var like os.name ('posix'/'nt' — note os.name returns 'nt' on Windows, not 'windows'), or copy-pasting config between platforms.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• CopilotClient(mode='empty') requires base_directory…
• Invalid entry '*': there is no bare wildcard. Use one or…
• Client is not connected. Call start() first.
• telemetry is not supported with…
• Set environment variables via either the client-level env…

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

Appendix: source

Thrown at python/copilot/client.py:422

    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"]
        wire[name] = config
    return wire

View on GitHub (pinned to cd8cf15dc3)