BabylonJS/Babylon.js · error

Session id must be a number.

Error message

Session id must be a number.

What it means

ValidateSessionId parses the --session CLI value as a base-10 integer and throws when it is not numeric, before looking the session up in the bridge's session list.

Source

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

async function WithBridge(bridgeScript: string | undefined, fn: (socket: WebSocket) => Promise<void>): Promise<void> {
    const socket = await EnsureBridge(Config.cliPort, bridgeScript);
    try {
        await fn(socket);
    } finally {
        socket.close();
    }
}

/**
 * Parses and validates an explicit session id string against the list of active sessions.
 * @param explicitId The session id string to validate.
 * @param sessions The list of active sessions from the bridge.
 * @returns The matching session info.
 */
export function ValidateSessionId(explicitId: string, sessions: SessionInfo[]): SessionInfo {
    const parsed = parseInt(explicitId, 10);
    if (isNaN(parsed)) {
        throw new Error("Session id must be a number.");
    }
    const match = sessions.find((s) => s.id === parsed);
    if (!match) {
        if (sessions.length === 0) {
            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.

View on GitHub (pinned to 0592b347b8)

Solutions

1. Pass the numeric session id: --session 1 instead of a name or non-numeric string.
2. Run the sessions-listing command (or --session without value flow) to discover valid numeric ids.
3. Sanitize shell scripts: ensure the variable interpolated into --session is a number (e.g. ${SESSION_ID:?}).

Example fix

// before
cli inspect --session "my-session" // throws
// after
cli sessions        // list ids
cli inspect --session 2

function isValidSessionIdArg(v: string | undefined): boolean {
  return v !== undefined && /^\d+$/.test(v);
}
if (!isValidSessionIdArg(explicitId)) throw new Error("--session must be a numeric id");

function isNumericId(v: string | undefined): v is string {
  return typeof v === "string" && /^\d+$/.test(v);
}

try {
  const session = ValidateSessionId(raw, sessions);
} catch (e) {
  if (e instanceof Error && e.message === "Session id must be a number.") {
    console.error(`--session must be numeric, got "${raw}". Run 'sessions' to list ids.`);
  } else throw e;
}

When it happens

Trigger: Passing --session with a non-numeric value (e.g. --session abc, --session "1,2", or an empty string) to a CLI command that resolves a target inspector session.

Common situations: Copy-pasting a session name instead of its numeric id; shell mangling the argument; scripting with a placeholder that was never substituted; confusing session name with session id.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Session ${parsed} does not exist. Active sessions: ${list}
• A session id is required. Use --session to list active sessi
• Sample2DRgbaToRef: widthPx and heightPx must be positive.
• At least one mesh is needed to create the nav mesh.
• At least one mesh is needed to create the nav mesh.

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