Invalid session ID "${trimmed}": Only alphanumeric character

Error message

Invalid session ID "${trimmed}": Only alphanumeric characters, dashes, and underscores are allowed.

What it means

Thrown inside the yargs `coerce` hook for `--session-id` when the trimmed value contains characters outside the allowed set `[a-zA-Z0-9-_]`. The ID is used to build filesystem paths and resume tokens, so characters like slashes, spaces, dots, or colons would corrupt path resolution or break downstream lookups. The regex rejects anything but alphanumerics, dashes, and underscores.

Source

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

            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',
          description:
            'Delete a session by index number (use --list-sessions to see available sessions).',
        })

View on GitHub (pinned to 5024443c72)

Solutions

Use only `a-z`, `A-Z`, `0-9`, `-`, and `_`: `gemini --session-id my_session-2026-01`.
Strip or replace disallowed characters before passing the value.
If you need a UUID, use the hyphenated form (already valid): `gemini --session-id 550e8400-e29b-41d4-a716-446655440000`.

Example fix

// before
gemini --session-id "my.session/01"
// after
gemini --session-id "my-session-01"

Defensive patterns

Strategy: validation

Validate before calling

const SESSION_ID_RE = /^[a-zA-Z0-9-_]+$/;
function assertSessionId(raw: string): string {
  const trimmed = raw.trim();
  if (!SESSION_ID_RE.test(trimmed)) {
    throw new Error(`Invalid session ID "${trimmed}": use a-z, A-Z, 0-9, -, _ only.`);
  }
  return trimmed;
}

Type guard

function isValidSessionId(v: unknown): v is string {
  return typeof v === 'string' && /^[a-zA-Z0-9-_]+$/.test(v);
}

Prevention

Restrict generated IDs to `[A-Za-z0-9-_]`.
Replace dots, slashes, and colons with dashes before passing.
Hyphenated UUIDs are already valid; don't wrap them in braces.

When it happens

Trigger: Passing a UUID with dots (`--session-id 01.abc`), slashes (`--session-id a/b`), colons, spaces, or any punctuation other than dash/underscore; passing a full UUID with curly braces; passing a file path.

Common situations: Treating session-id as a free-form label; pasting a UUID in a format that includes characters the regex forbids; using dots to separate version segments; non-ASCII characters.

Related errors

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