{"record":{"id":"a024a48c458376f4","repo":"github/copilot-sdk","slug":"sessionfs-conventions-must-be-either-windows-or","errorCode":null,"errorMessage":"sessionFs.conventions must be either 'windows' or 'posix'","messagePattern":"sessionFs\\.conventions must be either 'windows' or 'posix'","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nodejs/src/client.ts","lineNumber":808,"sourceCode":"\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            );\n        }\n        const provider = config.createSessionFsProvider(session);\n        if (this.sessionFsConfig.capabilities?.sqlite && !provider.sqlite) {\n            throw new Error(","sourceCodeStart":790,"sourceCodeEnd":826,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/nodejs/src/client.ts#L790-L826","documentation":"With sessionFs enabled, `validateSessionFsConfig` checks that `sessionFs.conventions` is exactly the string \"windows\" or \"posix\". This setting tells the library which path/case semantics to apply to the virtual filesystem; any other value (different case, typos, wrong type) is rejected at construction.","triggerScenarios":"Passing `conventions: \"Windows\"`, `\"POSIX\"`, `\"linux\"`, `\"unix\"`, `\"\"`, or a non-string value (e.g. true or process.platform output like \"win32\"/\"darwin\") in the sessionFs config.","commonSituations":"Using Node's process.platform value (\"win32\", \"darwin\") directly instead of \"windows\"/\"posix\"; inconsistent capitalization; YAML/JSON config with a misspelled enum; leaving conventions as undefined and relying on a default that does not exist.","solutions":["Set sessionFs.conventions to exactly \"windows\" or \"posix\" (lowercase).","Map platform strings explicitly: process.platform === \"win32\" ? \"windows\" : \"posix\".","If unsure on non-Windows platforms, use \"posix\" (Linux/macOS path semantics)."],"exampleFix":"// before\nsessionFs: { initialCwd, sessionStatePath, conventions: process.platform } // \"darwin\" -> throws\n// after\nsessionFs: { initialCwd, sessionStatePath, conventions: process.platform === \"win32\" ? \"windows\" : \"posix\" }","handlingStrategy":"type-guard","validationCode":"const CONVENTIONS = new Set([\"windows\", \"posix\"]);\nif (options.sessionFs && !CONVENTIONS.has(options.sessionFs.conventions))\n  throw new Error(`sessionFs.conventions must be 'windows' or 'posix', got: ${options.sessionFs.conventions}`);","typeGuard":"function isConventions(v) {\n  return v === \"windows\" || v === \"posix\";\n}","tryCatchPattern":"try {\n  const client = new CopilotClient({ sessionFs: cfg });\n} catch (err) {\n  if (err.message.includes(\"conventions must be\")) {\n    throw new Error(`Use exactly \"windows\" or \"posix\" (lowercase); got: ${cfg.conventions}`);\n  }\n  throw err;\n}","preventionTips":["Map process.platform (\"win32\"/\"darwin\"/\"linux\") to the enum instead of passing it directly.","Use a TypeScript union type ('windows' | 'posix') so invalid literals fail compilation.","Store conventions in config files as lowercase and validate on load."],"tags":["configuration","validation","enum","sessionfs"],"backgroundTag":"invalid-enum-value","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"}