What causes "Client is not connected. Call start() first." in github/copilot-sdk?

Change ask_user_variant to exactly "legacy" or "elicitation" (lowercase).

Client is not connected. Call start() first.

Error message

Client is not connected. Call start() first.

What it means

CopilotClient.create_session() validates the ask_user_variant argument against the fixed set (None, "legacy", "elicitation") and raises this ValueError for any other value. It selects which ask-user/permission-prompt protocol variant the session uses, so only the two named variants exist.

Solutions

Change ask_user_variant to exactly "legacy" or "elicitation" (lowercase).
Omit ask_user_variant entirely to use the library default (None).
If the value comes from user config, validate/normalize it (strip, lowercase) and check membership before the call.
Check the installed SDK version's supported variants if a documented value is rejected.

Example fix

// before
await client.create_session(ask_user_variant="Elicitation")
// after
await client.create_session(ask_user_variant="elicitation")

Defensive patterns

Strategy: validation

Validate before calling

VALID_VARIANTS = {None, "legacy", "elicitation"}
if ask_user_variant not in VALID_VARIANTS:
    raise ValueError('ask_user_variant must be "legacy" or "elicitation"')

Try / catch

try:
    await client.create_session(ask_user_variant=variant)
except ValueError as e:
    if "ask_user_variant" in str(e):
        await client.create_session()  # fall back to default

Prevention

Use an enum or Literal type for ask_user_variant in your wrappers.
Normalize config strings (strip/lowercase) before passing.
Never hardcode variant strings inline; use a shared constant.

When it happens

Trigger: Calling create_session(ask_user_variant=...) with a misspelled or unsupported value such as "Elicitation", "legacy ", "new", or a non-string value.

Common situations: Typo or wrong casing when copying an example; passing a config value read from YAML/JSON without normalization; copying a variant name from a newer or older SDK version that supports different values.

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

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

Appendix: source

Thrown at nodejs/src/client.ts:506

    private negotiatedProtocolVersion: number | null = null;
    /** Connection-level session filesystem config, set via constructor option. */
    private sessionFsConfig: SessionFsConfig | null = null;
    private requestHandler: CopilotRequestHandler | null = null;
    private builtinPluginDirectories: string[] = [];
    private onGitHubTelemetry?: (notification: GitHubTelemetryNotification) => void | Promise<void>;
    private clientGlobalHandlers: import("./generated/rpc.js").ClientGlobalApiHandlers = {};
    private githubTokenProviders = new Map<
        string,
        { provider: GitHubTokenProvider; sessionId?: string; committed: boolean }
    >();

    /**
     * Typed server-scoped RPC methods.
     * @throws Error if the client is not connected
     */
    get rpc(): ReturnType<typeof createServerRpc> {
        if (!this.connection) {
            throw new Error("Client is not connected. Call start() first.");
        }
        if (!this._rpc) {
            this._rpc = createServerRpc(this.connection);
        }
        return this._rpc;
    }

    /**
     * Internal RPC surface (e.g. handshake helpers). Not part of the public API.
     * @internal
     */
    private get internalRpc(): ReturnType<typeof createInternalServerRpc> {
        if (!this.connection) {
            throw new Error("Client is not connected. Call start() first.");
        }
        if (!this._internalRpc) {
            this._internalRpc = createInternalServerRpc(this.connection);
        }

View on GitHub (pinned to cd8cf15dc3)