github/copilot-sdk · error

CopilotClient is in mode: 'empty' but the session config…

Error message

CopilotClient is in mode: 'empty' but the session config did not specify 'availableTools'. Empty mode requires every session to explicitly opt into the tools it wants — e.g. `new ToolSet().addBuiltIn(BuiltInTools.Isolated)`.

What it means

Error "CopilotClient is in mode: 'empty' but the session config did not specify 'availableTools'. Empty mode requires every session to explicitly opt into the tools it wants — e.g. `new ToolSet().addBuiltIn(BuiltInTools.Isolated)`." thrown in github/copilot-sdk.

Solutions

1. Pass availableTools in the per-session config, e.g. new ToolSet().addBuiltIn(BuiltInTools.Isolated), converted to a list as required
2. Do not assume empty mode inherits default tools — every session must explicitly opt in
3. If all sessions should share a toolset, build the ToolSet once and reference it in each createSession call

When it happens

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

Appendix: source

Thrown at nodejs/src/client.ts:1376

     *
     * @internal
     */
    private resolveToolFilterOptions(config: {
        availableTools?: string[] | ToolSet;
        excludedTools?: string[] | ToolSet;
    }): {
        availableTools: string[] | undefined;
        excludedTools: string[] | undefined;
        toolFilterPrecedence: "excluded";
    } {
        const availableTools = toolFilterListToArray(config.availableTools);
        const excludedTools = toolFilterListToArray(config.excludedTools);
        validateToolFilterList("availableTools", availableTools);
        validateToolFilterList("excludedTools", excludedTools);

        if (this.options.mode === "empty") {
            if (availableTools === undefined) {
                throw new Error(
                    "CopilotClient is in mode: 'empty' but the session config did not " +
                        "specify 'availableTools'. Empty mode requires every session to " +
                        "explicitly opt into the tools it wants — e.g. " +
                        "`new ToolSet().addBuiltIn(BuiltInTools.Isolated)`."
                );
            }
        }

        return { availableTools, excludedTools, toolFilterPrecedence: "excluded" };
    }

    /** Mode-specific defaults spread under the caller's config (app values win). */
    private configDefaultsForMode(): Partial<SessionConfigBase> {
        if (this.options.mode === "empty") {
            return {
                enableSessionTelemetry: false,
                mcpOAuthTokenStorage: "in-memory",
                skipEmbeddingRetrieval: true,

View on GitHub (pinned to cd8cf15dc3)