github/copilot-sdk · error

sessionFs.sessionStatePath is required

Error message

sessionFs.sessionStatePath is required

What it means

`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.

Solutions

1. Set sessionFs.sessionStatePath to a non-empty writable file/directory path in the client options.
2. If the path is derived from a base directory, ensure the base directory variable is defined before building the config.
3. Confirm the target location is writable by the process before starting the client.

Example fix

// before
sessionFs: { initialCwd, conventions: "posix" } // sessionStatePath forgotten
// after
import path from "node:path";
const statePath = process.env.SESSION_STATE_DIR ?? path.join(initialCwd, ".copilot-session");
sessionFs: { initialCwd, sessionStatePath: statePath, conventions: "posix" }

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

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

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

When it happens

Trigger: Constructing CopilotClient with `sessionFs` enabled but `sessionStatePath` omitted, undefined, or an empty string, after initialCwd has passed validation.

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

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.initialCwd 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/c96c471938c8192e. Report an issue: GitHub.

Appendix: source

Thrown at nodejs/src/client.ts:804

        }

        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;
        }
        if (!config.createSessionFsProvider) {
            throw new Error(
                "createSessionFsProvider is required in session config when sessionFs is enabled in client options."
            );

View on GitHub (pinned to cd8cf15dc3)