github/copilot-sdk · error

CopilotClient was created with mode: 'empty' but neither…

Error message

CopilotClient was created with mode: 'empty' but neither 'baseDirectory' nor 'sessionFs' was set. Empty mode requires an explicit per-session persistence location; pick one.

What it means

Error "CopilotClient was created with mode: 'empty' but neither 'baseDirectory' nor 'sessionFs' was set. Empty mode requires an explicit per-session persistence location; pick one." thrown in github/copilot-sdk.

Solutions

1. Set baseDirectory to a dedicated empty directory per tenant/session in the CopilotClient options
2. Alternatively provide a sessionFs configuration with a custom SessionFsProvider for per-session persistence
3. Do not rely on the default ~/.copilot fallback in empty mode; it is intentionally rejected

When it happens

Trigger: Thrown at nodejs/src/client.ts:740 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/a2cccfd9016040b4. Report an issue: GitHub.

Appendix: source

Thrown at nodejs/src/client.ts:740

            enableRemoteSessions: options.enableRemoteSessions ?? false,
            mode: options.mode ?? "copilot-cli",
            clientInfo: options.clientInfo,
        };

        // Empty mode: validate at construction time that the app supplied a
        // per-session persistence location. The runtime is mode-agnostic, so
        // without this check it would silently fall back to ~/.copilot, which
        // defeats the point of empty mode for multi-tenant scenarios.
        if (this.options.mode === "empty") {
            const hasPersistence =
                this.options.baseDirectory !== undefined ||
                this.sessionFsConfig !== null ||
                // External runtimes manage their own persistence layer; the SDK
                // can't enforce it from here.
                conn.kind === "uri" ||
                conn.kind === "parent-process";
            if (!hasPersistence) {
                throw new Error(
                    "CopilotClient was created with mode: 'empty' but neither " +
                        "'baseDirectory' nor 'sessionFs' was set. Empty mode requires " +
                        "an explicit per-session persistence location; pick one."
                );
            }
        }
    }

    private connectionExtraArgs: string[] = [];

    /**
     * Parse CLI URL into host and port
     * Supports formats: "host:port", "[ipv6]:port", "http://host:port", "https://host:port", or just "port"
     */
    private parseCliUrl(url: string): { host: string; port: number } {
        // Remove protocol if present
        const cleanUrl = url.replace(/^https?:\/\//, "");

View on GitHub (pinned to cd8cf15dc3)