google-gemini/gemini-cli · error

The --session-id option cannot be empty.

Error message

The --session-id option cannot be empty.

What it means

Thrown inside the yargs `coerce` hook for `--session-id` when the user-supplied value, after trimming whitespace, is empty. The coerce runs only when the flag is present, so this fires for `--session-id ""` or whitespace-only values. The session ID is later used to resume a specific session, so an empty value is meaningless and rejected early.

Source

Thrown at packages/cli/src/config/config.ts:432

            if (trimmed === '') {
              return RESUME_LATEST;
            }
            return trimmed;
          },
        })
        .option('session-file', {
          type: 'string',
          nargs: 1,
          description: 'Load a session from a JSON file',
        })
        .option('session-id', {
          type: 'string',
          nargs: 1,
          description: 'Start a new session with a manually provided UUID.',
          coerce: (value: string): string => {
            const trimmed = value.trim();
            if (!trimmed) {
              throw new Error('The --session-id option cannot be empty.');
            }
            if (!/^[a-zA-Z0-9-_]+$/.test(trimmed)) {
              throw new Error(
                'Invalid session ID "' +
                  trimmed +
                  '": Only alphanumeric characters, dashes, and underscores are allowed.',
              );
            }
            return trimmed;
          },
        })
        .option('list-sessions', {
          type: 'boolean',
          description:
            'List available sessions for the current project and exit.',
        })
        .option('delete-session', {
          type: 'string',

View on GitHub (pinned to 5024443c72)

Solutions

1. Omit the flag entirely to let Gemini auto-generate a session ID.
2. Pass a concrete non-empty identifier: `gemini --session-id my-session-1`.
3. Guard the flag in scripts: `[ -n "$SID" ] && args+=(--session-id "$SID")`.

Example fix

// before
gemini --session-id ""
// after
gemini --session-id my-session-1

function normalizeSessionId(raw: string | undefined): string | undefined {
  if (raw === undefined) return undefined;
  const trimmed = raw.trim();
  if (!trimmed) {
    throw new Error('--session-id cannot be empty; omit the flag to auto-generate.');
  }
  return trimmed;
}

function isNonEmptyTrimmed(v: unknown): v is string {
  return typeof v === 'string' && v.trim().length > 0;
}

When it happens

Trigger: Running `gemini --session-id ""`, `gemini --session-id " "`, or passing the flag with an empty shell variable (`gemini --session-id "$SID"` with `SID` unset or empty).

Common situations: Scripted invocations that always pass the flag but forget to populate the variable; copy-paste templates that leave the value blank; CI jobs with an unbound `SESSION_ID` env var.

Related errors

• The source argument must be provided.
• The path argument must be provided.
• The skill name must be provided.
• Invalid session ID "${trimmed}": Only alphanumeric character
• Invalid scope: ${argv.scope}. Please use one of ${Object.val

AI-assisted analysis of google-gemini/gemini-cli@5024443c72 (2026-08-12). Data as JSON: /api/errors/a1f458b238269721. Report an issue: GitHub.