createSessionFsProvider is required in session config when…

Error message

createSessionFsProvider is required in session config when sessionFs is enabled in client options.

What it means

`setupSessionFs` runs per session when sessionFs is enabled at the client level. It requires each session's config to supply a `createSessionFsProvider` factory, because enabling sessionFs globally only declares intent — each session must provide the actual provider implementation. The library throws when the client-level sessionFs config exists but the session config lacks the factory.

Solutions

Add `createSessionFsProvider: (session) => yourProvider` to every session config passed to createSession.
If the session should not use sessionFs, either supply a provider anyway or disable sessionFs in the client options.
If sqlite capability is declared (sessionFs.capabilities.sqlite), make sure the returned provider also implements the sqlite surface or remove that capability.

Example fix

// before
const client = new CopilotClient({ sessionFs: { initialCwd, sessionStatePath, conventions: "posix" } });
client.createSession({ ... }); // no provider
// after
client.createSession({
  ...,
  createSessionFsProvider: (session) => ({ /* implements SessionFsProvider */ })
});

Defensive patterns

Strategy: validation

Validate before calling

function assertSessionProvider(clientOpts, sessionCfg) {
  if (clientOpts.sessionFs && typeof sessionCfg.createSessionFsProvider !== "function")
    throw new Error("sessionFs is enabled in client options; session config must define createSessionFsProvider");
}
assertSessionProvider(clientOptions, sessionConfig);

Type guard

function hasFsProvider(cfg) {
  return typeof cfg === "object" && cfg !== null && typeof cfg.createSessionFsProvider === "function";
}

Try / catch

try {
  const session = await client.createSession(sessionConfig);
} catch (err) {
  if (err.message.includes("createSessionFsProvider is required")) {
    throw new Error("Add createSessionFsProvider to every session config while sessionFs is enabled");
  }
  throw err;
}

Prevention

Wrap createSession in a helper that injects a default createSessionFsProvider when sessionFs is enabled.
Keep session configs in one place; avoid hand-rolled config objects scattered across call sites.
If declaring capabilities.sqlite, also assert the provider implements sqlite at creation time to catch the follow-up error early.

When it happens

Trigger: Creating CopilotClient with `sessionFs: {...}` in client options, then calling `createSession` / starting a session whose config object does not include `createSessionFsProvider: (session) => SessionFsProvider`.

Common situations: Enabling the feature flag in shared client options while reusing older per-session config objects written before sessionFs existed; multiple session configs where one was missed; docs/examples that only show the client option and omit the per-session provider.

Understand the failure class

Background: "Must pass :limit option" / "Missing required option" — required option errors explained — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at nodejs/src/client.ts:820

        if (!config.sessionStatePath) {
            throw new Error("sessionFs.sessionStatePath is required");
        }

        if (config.conventions !== "windows" && config.conventions !== "posix") {
            throw new Error("sessionFs.conventions must be either 'windows' or 'posix'");
        }
    }

    private setupSessionFs(
        session: CopilotSession,
        config: { createSessionFsProvider?: (session: CopilotSession) => SessionFsProvider }
    ): void {
        if (!this.sessionFsConfig) {
            return;
        }
        if (!config.createSessionFsProvider) {
            throw new Error(
                "createSessionFsProvider is required in session config when sessionFs is enabled in client options."
            );
        }
        const provider = config.createSessionFsProvider(session);
        if (this.sessionFsConfig.capabilities?.sqlite && !provider.sqlite) {
            throw new Error(
                "SessionFsConfig declares capabilities.sqlite but the provider does not implement sqlite."
            );
        }
        session.clientSessionApis.sessionFs = createSessionFsAdapter(provider);
    }

    private setupClientGlobalHandlers(): void {
        const handlers: import("./generated/rpc.js").ClientGlobalApiHandlers = {};
        if (this.requestHandler) {
            handlers.llmInference = createCopilotRequestAdapter(this.requestHandler, () => {
                if (!this.connection) {
                    return undefined;

View on GitHub (pinned to cd8cf15dc3)