{"record":{"id":"d0f0e7a82e1b0470","repo":"github/copilot-sdk","slug":"createsessionfsprovider-is-required-in-session-con","errorCode":null,"errorMessage":"createSessionFsProvider is required in session config when sessionFs is enabled in client options.","messagePattern":"createSessionFsProvider is required in session config when sessionFs is enabled in client options\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nodejs/src/client.ts","lineNumber":820,"sourceCode":"\n        if (!config.sessionStatePath) {\n            throw new Error(\"sessionFs.sessionStatePath is required\");\n        }\n\n        if (config.conventions !== \"windows\" && config.conventions !== \"posix\") {\n            throw new Error(\"sessionFs.conventions must be either 'windows' or 'posix'\");\n        }\n    }\n\n    private setupSessionFs(\n        session: CopilotSession,\n        config: { createSessionFsProvider?: (session: CopilotSession) => SessionFsProvider }\n    ): void {\n        if (!this.sessionFsConfig) {\n            return;\n        }\n        if (!config.createSessionFsProvider) {\n            throw new Error(\n                \"createSessionFsProvider is required in session config when sessionFs is enabled in client options.\"\n            );\n        }\n        const provider = config.createSessionFsProvider(session);\n        if (this.sessionFsConfig.capabilities?.sqlite && !provider.sqlite) {\n            throw new Error(\n                \"SessionFsConfig declares capabilities.sqlite but the provider does not implement sqlite.\"\n            );\n        }\n        session.clientSessionApis.sessionFs = createSessionFsAdapter(provider);\n    }\n\n    private setupClientGlobalHandlers(): void {\n        const handlers: import(\"./generated/rpc.js\").ClientGlobalApiHandlers = {};\n        if (this.requestHandler) {\n            handlers.llmInference = createCopilotRequestAdapter(this.requestHandler, () => {\n                if (!this.connection) {\n                    return undefined;","sourceCodeStart":802,"sourceCodeEnd":838,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/nodejs/src/client.ts#L802-L838","documentation":"`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.","triggerScenarios":"Creating CopilotClient with `sessionFs: {...}` in client options, then calling `createSession` / starting a session whose config object does not include `createSessionFsProvider: (session) => SessionFsProvider`.","commonSituations":"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.","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."],"exampleFix":"// before\nconst client = new CopilotClient({ sessionFs: { initialCwd, sessionStatePath, conventions: \"posix\" } });\nclient.createSession({ ... }); // no provider\n// after\nclient.createSession({\n  ...,\n  createSessionFsProvider: (session) => ({ /* implements SessionFsProvider */ })\n});","handlingStrategy":"validation","validationCode":"function assertSessionProvider(clientOpts, sessionCfg) {\n  if (clientOpts.sessionFs && typeof sessionCfg.createSessionFsProvider !== \"function\")\n    throw new Error(\"sessionFs is enabled in client options; session config must define createSessionFsProvider\");\n}\nassertSessionProvider(clientOptions, sessionConfig);","typeGuard":"function hasFsProvider(cfg) {\n  return typeof cfg === \"object\" && cfg !== null && typeof cfg.createSessionFsProvider === \"function\";\n}","tryCatchPattern":"try {\n  const session = await client.createSession(sessionConfig);\n} catch (err) {\n  if (err.message.includes(\"createSessionFsProvider is required\")) {\n    throw new Error(\"Add createSessionFsProvider to every session config while sessionFs is enabled\");\n  }\n  throw err;\n}","preventionTips":["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."],"tags":["configuration","sessionfs","required-field","provider"],"backgroundTag":"missing-required-option","analyzedSha":"cd8cf15dc3f9e762615790aaed0a771a0f392755","analyzedAt":"2026-09-09T18:32:31.973Z","contentChangedAt":"2026-09-09T18:32:31.973Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}