github/copilot-sdk · error

sessionFs.conventions must be either 'windows' or 'posix'

Error message

sessionFs.conventions must be either 'windows' or 'posix'

What it means

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.

Solutions

1. Set sessionFs.conventions to exactly "windows" or "posix" (lowercase).
2. Map platform strings explicitly: process.platform === "win32" ? "windows" : "posix".
3. If unsure on non-Windows platforms, use "posix" (Linux/macOS path semantics).

Example fix

// before
sessionFs: { initialCwd, sessionStatePath, conventions: process.platform } // "darwin" -> throws
// after
sessionFs: { initialCwd, sessionStatePath, conventions: process.platform === "win32" ? "windows" : "posix" }

const CONVENTIONS = new Set(["windows", "posix"]);
if (options.sessionFs && !CONVENTIONS.has(options.sessionFs.conventions))
  throw new Error(`sessionFs.conventions must be 'windows' or 'posix', got: ${options.sessionFs.conventions}`);

function isConventions(v) {
  return v === "windows" || v === "posix";
}

try {
  const client = new CopilotClient({ sessionFs: cfg });
} catch (err) {
  if (err.message.includes("conventions must be")) {
    throw new Error(`Use exactly "windows" or "posix" (lowercase); got: ${cfg.conventions}`);
  }
  throw err;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• sessionFs.initialCwd is required
• sessionFs.sessionStatePath is required
• SessionFS.SessionStatePath is required
• SessionFS.Conventions must be either 'posix' or 'windows'
• err.Error()

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

Appendix: source

Thrown at nodejs/src/client.ts:808

        if (isNaN(port) || port <= 0 || port > 65535) {
            throw new Error(`Invalid port in cliUrl: ${url}`);
        }

        return { host, port };
    }

    private validateSessionFsConfig(config: SessionFsConfig): void {
        if (!config.initialCwd) {
            throw new Error("sessionFs.initialCwd is required");
        }

        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(

View on GitHub (pinned to cd8cf15dc3)