{"record":{"id":"c96c471938c8192e","repo":"github/copilot-sdk","slug":"sessionfs-sessionstatepath-is-required","errorCode":null,"errorMessage":"sessionFs.sessionStatePath is required","messagePattern":"sessionFs\\.sessionStatePath is required","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nodejs/src/client.ts","lineNumber":804,"sourceCode":"        }\n\n        const host = parts[0] || \"localhost\";\n        const port = parseInt(parts[1], 10);\n\n        if (isNaN(port) || port <= 0 || port > 65535) {\n            throw new Error(`Invalid port in cliUrl: ${url}`);\n        }\n\n        return { host, port };\n    }\n\n    private validateSessionFsConfig(config: SessionFsConfig): void {\n        if (!config.initialCwd) {\n            throw new Error(\"sessionFs.initialCwd is required\");\n        }\n\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            );","sourceCodeStart":786,"sourceCodeEnd":822,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/nodejs/src/client.ts#L786-L822","documentation":"`validateSessionFsConfig` runs when sessionFs is enabled and requires `sessionFs.sessionStatePath` to be a truthy string. sessionStatePath is where the session's persistent state is stored; the library throws at construction time if it is missing so state is never silently lost.","triggerScenarios":"Constructing CopilotClient with `sessionFs` enabled but `sessionStatePath` omitted, undefined, or an empty string, after initialCwd has passed validation.","commonSituations":"Copying a config snippet that only showed initialCwd; forgetting to wire a per-session state directory from settings; empty string produced by joining an undefined base path; migrations to a newer library version that added the sessionStatePath requirement.","solutions":["Set sessionFs.sessionStatePath to a non-empty writable file/directory path in the client options.","If the path is derived from a base directory, ensure the base directory variable is defined before building the config.","Confirm the target location is writable by the process before starting the client."],"exampleFix":"// before\nsessionFs: { initialCwd, conventions: \"posix\" } // sessionStatePath forgotten\n// after\nimport path from \"node:path\";\nconst statePath = process.env.SESSION_STATE_DIR ?? path.join(initialCwd, \".copilot-session\");\nsessionFs: { initialCwd, sessionStatePath: statePath, conventions: \"posix\" }","handlingStrategy":"validation","validationCode":"function validateSessionFs(cfg) {\n  if (!cfg || typeof cfg.sessionStatePath !== \"string\" || cfg.sessionStatePath.length === 0)\n    throw new Error(\"sessionFs.sessionStatePath must be a non-empty string\");\n}\nvalidateSessionFs(options.sessionFs);","typeGuard":"function hasSessionStatePath(cfg) {\n  return typeof cfg === \"object\" && cfg !== null && typeof cfg.sessionStatePath === \"string\" && cfg.sessionStatePath.length > 0;\n}","tryCatchPattern":"try {\n  const client = new CopilotClient({ sessionFs: cfg });\n} catch (err) {\n  if (err.message === \"sessionFs.sessionStatePath is required\") {\n    throw new Error(\"Provide a non-empty sessionStatePath in sessionFs options\");\n  }\n  throw err;\n}","preventionTips":["Derive sessionStatePath with path.join from a base dir that is itself validated as non-empty.","Create the state directory with fs.mkdirSync(dir, { recursive: true }) before client construction.","Keep a single typed config builder so no field is forgotten when copying examples."],"tags":["configuration","validation","sessionfs","required-field"],"backgroundTag":"missing-required-config-field","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"}