A session id is required. Use --session to list active sessi

Error message

A session id is required. Use --session to list active sessions, then pass --session <id>.

What it means

ResolveSessionId requires an explicit --session value; when it is undefined it throws with instructions to list sessions and pass an id. It never guesses a default session.

Source

Thrown at packages/dev/inspector-v2/src/cli/cli.ts:265

            throw new Error(`Session ${parsed} does not exist. No active sessions.`);
        }
        const list = sessions.map((s) => `  [${s.id}] ${s.name}`).join("\n");
        throw new Error(`Session ${parsed} does not exist. Active sessions:\n${list}`);
    }
    return match;
}

/**
 * Resolves and validates the session id. Requires an explicit session id
 * provided via `--session <id>`. Throws if the id is missing, non-numeric,
 * or does not match an active session.
 * @param socket The WebSocket connection to the bridge.
 * @param explicitId The session id string from --session.
 * @returns The validated numeric session id.
 */
export async function ResolveSessionId(socket: WebSocket, explicitId: string | undefined): Promise<number> {
    if (explicitId === undefined) {
        throw new Error("A session id is required. Use --session to list active sessions, then pass --session <id>.");
    }

    const response = await SendAndReceive<SessionsResponse>(socket, { type: "sessions" });
    return ValidateSessionId(explicitId, response.sessions).id;
}

/**
 * Parses command arguments from the rest array (everything after the command id).
 * @param rest The remaining CLI tokens after the command id.
 * @param globalHelp Whether --help was specified at the top level.
 * @returns The parsed command arguments and whether help was requested.
 */
export function ParseCommandArgs(rest: string[], globalHelp: boolean): { args: Record<string, string>; wantsHelp: boolean } {
    const args: Record<string, string> = {};
    let wantsHelp = globalHelp;
    for (let i = 1; i < rest.length; i++) {
        const token = rest[i];
        if (token === "--help") {

View on GitHub (pinned to 0592b347b8)

Solutions

Add --session <id> to the command; run the sessions-listing command first to obtain the id.
In scripts, fail fast when the session variable is empty rather than silently omitting the flag.
If only one session is typically active, capture its id automatically from the sessions response and pass it explicitly.

Example fix

// before
cli inspect               # missing --session
// after
ID=$(cli sessions --first-id)
cli inspect --session "$ID"

Defensive patterns

Strategy: validation

Validate before calling

function requireSessionFlag(v: string | undefined): string {
  if (v === undefined || v === "") {
    throw new Error("--session is required. Run 'sessions' to list ids, then pass --session <id>.");
  }
  return v;
}

Type guard

function hasSessionId(v: string | undefined): v is string {
  return typeof v === "string" && v.length > 0;
}

Try / catch

try {
  const id = await ResolveSessionId(socket, explicitId);
} catch (e) {
  if (e instanceof Error && e.message.includes("A session id is required")) {
    const sessions = await SendAndReceive<SessionsResponse>(socket, { type: "sessions" });
    console.error(`--session required. Active sessions:\n${sessions.sessions.map((s) => `  [${s.id}] ${s.name}`).join("\n")}`);
  } else throw e;
}

Prevention

Always pass --session in scripts; validate the variable is non-empty before invoking
Implement auto-discovery: if only one session is active, still fetch and pass its id explicitly
Update CLI usage/docs so invocations include --session

When it happens

Trigger: Running a CLI command that needs a target session without the --session flag, e.g. omitting it in an interactive run or a script where the argument was dropped.

Common situations: Forgetting the flag when multiple sessions exist; shell script variable empty so --session is omitted entirely; following outdated docs that predate the --session requirement.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of BabylonJS/Babylon.js@0592b347b8 (2026-08-30). Data as JSON: /api/errors/b39635d1441ffe5b. Report an issue: GitHub.