{"record":{"id":"ff008a17a28cb5e9","repo":"github/copilot-sdk","slug":"sessionfs-initialcwd-is-required","errorCode":null,"errorMessage":"sessionFs.initialCwd is required","messagePattern":"sessionFs\\.initialCwd is required","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nodejs/src/client.ts","lineNumber":800,"sourceCode":"        if (parts.length !== 2) {\n            throw new Error(\n                `Invalid cliUrl format: ${url}. Expected \"host:port\", \"[ipv6]:port\", \"http://host:port\", or \"port\"`\n            );\n        }\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        }","sourceCodeStart":782,"sourceCodeEnd":818,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/nodejs/src/client.ts#L782-L818","documentation":"When `sessionFs` is enabled in CopilotClient options, `validateSessionFsConfig` requires `sessionFs.initialCwd` to be a truthy string. initialCwd is the working directory every sessionFs-backed session starts in; without it the library cannot anchor the virtual filesystem, so it fails fast at client/session construction instead of later at runtime.","triggerScenarios":"Passing `new CopilotClient({ sessionFs: { ... } })` with `initialCwd` omitted, set to undefined/null, or set to an empty string \"\" (falsy and therefore rejected).","commonSituations":"Building the sessionFs config object dynamically from env/CLI args where the cwd argument was never provided; spreading a partial config; empty-string defaults from shell variable interpolation (`CWD=\"\"`).","solutions":["Provide a non-empty absolute path for sessionFs.initialCwd in the client options.","If the value comes from an env var or CLI flag, check it is non-empty before constructing CopilotClient.","If you do not intend to use the sessionFs feature, remove the sessionFs option entirely instead of passing an empty config."],"exampleFix":"// before\nnew CopilotClient({ sessionFs: { initialCwd: process.env.WORKDIR ?? \"\", sessionStatePath, conventions: \"posix\" } });\n// after\nconst initialCwd = process.env.WORKDIR;\nif (!initialCwd) throw new Error(\"WORKDIR env var must be set\");\nnew CopilotClient({ sessionFs: { initialCwd, sessionStatePath, conventions: \"posix\" } });","handlingStrategy":"validation","validationCode":"function validateSessionFs(cfg) {\n  if (!cfg || typeof cfg.initialCwd !== \"string\" || cfg.initialCwd.length === 0)\n    throw new Error(\"sessionFs.initialCwd must be a non-empty string\");\n}\nvalidateSessionFs(options.sessionFs);","typeGuard":"function hasInitialCwd(cfg) {\n  return typeof cfg === \"object\" && cfg !== null && typeof cfg.initialCwd === \"string\" && cfg.initialCwd.length > 0;\n}","tryCatchPattern":"try {\n  const client = new CopilotClient({ sessionFs: cfg });\n} catch (err) {\n  if (err.message === \"sessionFs.initialCwd is required\") {\n    throw new Error(\"Provide a non-empty initialCwd in sessionFs options\");\n  }\n  throw err;\n}","preventionTips":["Build sessionFs config through a single factory function that asserts all fields.","Treat empty strings as missing: use `?? undefined` so defaults kick in and the error is clearer.","TypeScript users: make initialCwd a required non-optional field in the config type so omission fails at compile time."],"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"}