github/copilot-sdk · error

sessionFs.initialCwd is required

Error message

sessionFs.initialCwd is required

What it means

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.

Solutions

1. Provide a non-empty absolute path for sessionFs.initialCwd in the client options.
2. If the value comes from an env var or CLI flag, check it is non-empty before constructing CopilotClient.
3. If you do not intend to use the sessionFs feature, remove the sessionFs option entirely instead of passing an empty config.

Example fix

// before
new CopilotClient({ sessionFs: { initialCwd: process.env.WORKDIR ?? "", sessionStatePath, conventions: "posix" } });
// after
const initialCwd = process.env.WORKDIR;
if (!initialCwd) throw new Error("WORKDIR env var must be set");
new CopilotClient({ sessionFs: { initialCwd, sessionStatePath, conventions: "posix" } });

function validateSessionFs(cfg) {
  if (!cfg || typeof cfg.initialCwd !== "string" || cfg.initialCwd.length === 0)
    throw new Error("sessionFs.initialCwd must be a non-empty string");
}
validateSessionFs(options.sessionFs);

function hasInitialCwd(cfg) {
  return typeof cfg === "object" && cfg !== null && typeof cfg.initialCwd === "string" && cfg.initialCwd.length > 0;
}

try {
  const client = new CopilotClient({ sessionFs: cfg });
} catch (err) {
  if (err.message === "sessionFs.initialCwd is required") {
    throw new Error("Provide a non-empty initialCwd in sessionFs options");
  }
  throw err;
}

When it happens

Trigger: Passing `new CopilotClient({ sessionFs: { ... } })` with `initialCwd` omitted, set to undefined/null, or set to an empty string "" (falsy and therefore rejected).

Common situations: 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=""`).

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• sessionFs.sessionStatePath is required
• sessionFs.conventions must be either 'windows' or 'posix'
• createSessionFsProvider is required in session config when…
• SessionFS.SessionStatePath is required
• err.Error()

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

Appendix: source

Thrown at nodejs/src/client.ts:800

        if (parts.length !== 2) {
            throw new Error(
                `Invalid cliUrl format: ${url}. Expected "host:port", "[ipv6]:port", "http://host:port", or "port"`
            );
        }

        const host = parts[0] || "localhost";
        const port = parseInt(parts[1], 10);

        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;
        }

View on GitHub (pinned to cd8cf15dc3)