github/copilot-sdk · error

connectionToken must be a non-empty string

Error message

connectionToken must be a non-empty string

What it means

resume_session() validates ask_user_variant against the allowed set (None, "legacy", "elicitation") and raises this ValueError for any other value. It chooses the ask-user prompt protocol for the resumed session; only these two variants are implemented.

Solutions

1. Use exactly "legacy" or "elicitation" (lowercase) or omit the argument for the default.
2. Normalize/validate externally supplied values before passing them in.
3. Verify the installed SDK version supports the variant you intend to use.

Example fix

// before
await client.resume_session("session-123", ask_user_variant="Elicitation")
// after
await client.resume_session("session-123", ask_user_variant="elicitation")

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

try:
    await client.resume_session("session-123", ask_user_variant=variant)
except ValueError as e:
    if "ask_user_variant" in str(e):
        await client.resume_session("session-123")  # default variant

When it happens

Trigger: Calling resume_session(ask_user_variant=...) with any value other than exactly "legacy" or "elicitation" (wrong casing, whitespace, synonyms like "new", or non-string values from unvalidated config).

Common situations: Copy-paste from docs for a different SDK version; config values read from YAML/JSON without normalization; case-sensitive comparison tripping up values like "Elicitation".

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

• Client is not connected. Call start() first.
• Invalid entry '*': there is no bare wildcard. Use one or…
• telemetry is not supported with…
• Set environment variables via either the client-level env…
• on_permission_request must be callable when provided.

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

Appendix: source

Thrown at nodejs/src/client.ts:648

                    "is lowered to environment variables read by native runtime code running in the shared " +
                    "host process, so per-client telemetry cannot be honored in-process. Configure telemetry " +
                    "via the host process environment, or use a child-process transport."
            );
        }
        if (
            (conn.kind === "stdio" || conn.kind === "tcp") &&
            conn.env !== undefined &&
            options.env !== undefined
        ) {
            throw new Error(
                "Set environment variables via either the client-level env option or the connection's env " +
                    "(RuntimeConnection.forStdio/forTcp), not both. Prefer the connection-level env for " +
                    "child-process transports."
            );
        }
        if (conn.kind === "tcp" && conn.connectionToken !== undefined) {
            if (typeof conn.connectionToken !== "string" || conn.connectionToken.length === 0) {
                throw new Error("connectionToken must be a non-empty string");
            }
        }

        this.connectionConfig = conn;

        if (options.sessionFs) {
            this.validateSessionFsConfig(options.sessionFs);
        }
        if (options.builtinPluginDirectories) {
            for (const path of options.builtinPluginDirectories) {
                if (!isAbsolute(path)) {
                    throw new Error(
                        `builtinPluginDirectories must contain only absolute paths: ${path}`
                    );
                }
            }
            this.builtinPluginDirectories = [...options.builtinPluginDirectories];
        }

View on GitHub (pinned to cd8cf15dc3)