github/copilot-sdk · error · ValueError

Missing required field 'cwd' in SessionContext

Error message

Missing required field 'cwd' in SessionContext

What it means

SessionContext.from_dict requires the 'cwd' key in the session context payload and raises ValueError when absent or None. 'cwd' is mapped to working_directory, which the library treats as mandatory; gitRoot/repository/branch are optional.

Solutions

  1. Ensure the event producer includes 'cwd' in the SessionContext payload
  2. Remap alternate keys before decoding: obj.setdefault('cwd', obj.get('workingDirectory'))
  3. Always provide session_fs.initial_working_directory when creating the session so the server can report cwd
  4. Fix fixtures/mocks to include 'cwd'

Example fix

// before
SessionContext.from_dict({"gitRoot": "/repo"})
// after
SessionContext.from_dict({"cwd": "/repo", "gitRoot": "/repo"})
Defensive patterns

Strategy: type-guard

Validate before calling

def has_cwd(obj) -> bool:
    return isinstance(obj, dict) and obj.get("cwd") is not None

Type guard

def is_session_context_payload(obj: object) -> bool:
    return isinstance(obj, dict) and isinstance(obj.get("cwd"), str)

Try / catch

try:
    ctx = SessionContext.from_dict(payload)
except ValueError as e:
    if "Missing required field 'cwd'" in str(e):
        payload.setdefault("cwd", os.getcwd())
        ctx = SessionContext.from_dict(payload)
    else:
        raise

Prevention

When it happens

Trigger: A session-update/context event arrives without 'cwd'; the producer sends 'workingDirectory' or 'working_directory' instead of 'cwd'; the session was created without a working directory.

Common situations: Sessions started without an initial working directory on the server; key-renaming across server versions or intermediaries; test fixtures omitting cwd.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at python/copilot/client.py:1200

# Session Metadata Types
# ============================================================================


@dataclass
class SessionContext:
    """Working directory context for a session"""

    working_directory: str  # Working directory where the session was created
    git_root: str | None = None  # Git repository root (if in a git repo)
    repository: str | None = None  # GitHub repository in "owner/repo" format
    branch: str | None = None  # Current git branch

    @staticmethod
    def from_dict(obj: Any) -> SessionContext:
        assert isinstance(obj, dict)
        cwd = obj.get("cwd")
        if cwd is None:
            raise ValueError("Missing required field 'cwd' in SessionContext")
        return SessionContext(
            working_directory=str(cwd),
            git_root=obj.get("gitRoot"),
            repository=obj.get("repository"),
            branch=obj.get("branch"),
        )

    def to_dict(self) -> dict:
        result: dict = {"cwd": self.working_directory}
        if self.git_root is not None:
            result["gitRoot"] = self.git_root
        if self.repository is not None:
            result["repository"] = self.repository
        if self.branch is not None:
            result["branch"] = self.branch
        return result

View on GitHub (pinned to cd8cf15dc3)