github/copilot-sdk · error · ValueError

invalid systemMessage.transform payload

Error message

invalid systemMessage.transform payload

What it means

Raised by the systemMessage.transform handler when the callback payload lacks either a truthy 'sessionId' or a non-empty 'sections' value. Both are required to route and apply the transform, so the payload is rejected with a ValueError.

Solutions

1. Update the Copilot CLI so systemMessage.transform always carries sessionId and a non-empty sections list
2. Log the params dict to see which of the two required fields is missing
3. If emitting the request manually, supply both sessionId and sections (non-empty list)
4. Catch ValueError around dispatch and return an error response to the server

Example fix

// before
await client._handle_system_message_transform({"sessionId": sid})
// after
await client._handle_system_message_transform({"sessionId": sid, "sections": ["instructions"]})

def valid_transform_params(p):
    return isinstance(p, dict) and bool(p.get("sessionId")) and bool(p.get("sections"))

def has_id_and_sections(p) -> bool:
    return (
        isinstance(p, dict)
        and bool(p.get("sessionId"))
        and isinstance(p.get("sections"), (list, dict))
        and len(p["sections"]) > 0
    )

try:
    await client._handle_system_message_transform(params)
except ValueError as e:
    logger.error("bad systemMessage.transform payload: %s | params=%r", e, params)

When it happens

Trigger: The CLI server sends a systemMessage.transform request where params['sessionId'] is missing/empty or params['sections'] is missing, None, or an empty collection.

Common situations: CLI/SDK schema mismatch after an upgrade, a CLI build that omits sections when there is nothing to transform, or a test harness sending a minimal params dict.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Invalid systemMessage.transform payload
• invalid user input request payload
• invalid exit plan mode request payload
• invalid auto mode switch request payload
• Invalid user input request payload

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

Appendix: source

Thrown at python/copilot/client.py:4994

        session_id = params.get("sessionId")
        if not session_id:
            raise ValueError("invalid auto mode switch request payload")

        with self._sessions_lock:
            session = self._sessions.get(session_id)
        if not session:
            raise ValueError(f"unknown session {session_id}")

        response = await session._handle_auto_mode_switch_request(params)
        return {"response": response}

    async def _handle_system_message_transform(self, params: dict) -> dict:
        """Handle a systemMessage.transform request from the CLI server."""
        session_id = params.get("sessionId")
        sections = params.get("sections")

        if not session_id or not sections:
            raise ValueError("invalid systemMessage.transform payload")

        with self._sessions_lock:
            session = self._sessions.get(session_id)
        if not session:
            raise ValueError(f"unknown session {session_id}")

        return await session._handle_system_message_transform(sections)

View on GitHub (pinned to cd8cf15dc3)