github/copilot-sdk · error · ValueError

ask_user_variant must be "legacy" or "elicitation"

Error message

ask_user_variant must be "legacy" or "elicitation"

What it means

Input validation in CopilotClient.create_session: ask_user_variant was given a value other than the two supported wire values "legacy" or "elicitation". The variant selects how ask-user prompts are delivered by the runtime; any other string is rejected before session.create is issued.

Solutions

1. Pass ask_user_variant="legacy" for the classic prompt flow
2. Pass ask_user_variant="elicitation" for the elicitation-style flow
3. Omit the argument to use the server default instead of guessing a value

When it happens

Trigger: Thrown at python/copilot/client.py:2535 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at python/copilot/client.py:2535

        Example:
            >>> session = await client.create_session(
            ...     on_permission_request=PermissionHandler.approve_all,
            ... )
            >>>
            >>> # Session with model and streaming
            >>> session = await client.create_session(
            ...     on_permission_request=PermissionHandler.approve_all,
            ...     model="gpt-4",
            ...     streaming=True,
            ... )
        """
        if on_permission_request is not None and not callable(on_permission_request):
            raise ValueError("on_permission_request must be callable when provided.")
        if github_token is not None and github_token_provider is not None:
            raise ValueError("github_token and github_token_provider are mutually exclusive")
        if ask_user_variant not in (None, "legacy", "elicitation"):
            raise ValueError('ask_user_variant must be "legacy" or "elicitation"')
        if not self._client:
            await self.start()

        tool_defs = []
        if tools:
            for tool in tools:
                definition: dict[str, Any] = {
                    "name": tool.name,
                    "description": tool.description,
                }
                if tool.parameters:
                    definition["parameters"] = tool.parameters
                if tool.overrides_built_in_tool:
                    definition["overridesBuiltInTool"] = True
                if tool.skip_permission:
                    definition["skipPermission"] = True
                if tool.defer is not None:
                    definition["defer"] = tool.defer

View on GitHub (pinned to cd8cf15dc3)