Invalid scope: ${argv.scope}. Please use one of ${Object.val

Error message

Invalid scope: ${argv.scope}. Please use one of ${Object.values(SettingScope).map((s) => s.toLowerCase()).join(', ')}.

What it means

The 'gemini extensions disable' command's --scope option is validated in a yargs .check() against the lowercased values of the SettingScope enum: user, workspace, system, systemdefaults, session. An unrecognized value fails validation and aborts before the handler runs. The default scope is User.

Source

Thrown at packages/cli/src/commands/extensions/disable.ts:69

  builder: (yargs) =>
    yargs
      .positional('name', {
        describe: 'The name of the extension to disable.',
        type: 'string',
      })
      .option('scope', {
        describe: 'The scope to disable the extension in.',
        type: 'string',
        default: SettingScope.User,
      })
      .check((argv) => {
        if (
          argv.scope &&
          !Object.values(SettingScope)
            .map((s) => s.toLowerCase())
            .includes(argv.scope.toLowerCase())
        ) {
          throw new Error(
            `Invalid scope: ${argv.scope}. Please use one of ${Object.values(
              SettingScope,
            )
              .map((s) => s.toLowerCase())
              .join(', ')}.`,
          );
        }
        return true;
      }),
  handler: async (argv) => {
    await handleDisable({
      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
      name: argv['name'] as string,
      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
      scope: argv['scope'] as string,
    });
    await exitCli();
  },

View on GitHub (pinned to 5024443c72)

Solutions

Use one of the valid scope values (case-insensitive): user, workspace, system, systemdefaults, session.
Omit --scope entirely to use the default (User).
Run 'gemini extensions disable --help' to see accepted values.

Example fix

// before
gemini extensions disable my-ext --scope project  // invalid

// after
gemini extensions disable my-ext --scope workspace  // valid

Defensive patterns

Strategy: validation

Validate before calling

import { SettingScope } from '../../config/settings.js';

function isValidScope(scope: string): boolean {
  return Object.values(SettingScope)
    .map((s) => s.toLowerCase())
    .includes(scope.toLowerCase());
}

// Before calling disable:
if (scope && !isValidScope(scope)) {
  throw new Error(`Use one of: ${Object.values(SettingScope).map((s) => s.toLowerCase()).join(', ')}`);
}

Type guard

import { SettingScope } from '../../config/settings.js';

function isValidSettingScope(value: string): value is string {
  return Object.values(SettingScope)
    .map((s) => s.toLowerCase())
    .includes(value.toLowerCase());
}

Prevention

Use tab-completion or --help to see valid scope values.
Omit --scope to use the default (User) when unsure.
Remember valid values: user, workspace, system, systemdefaults, session.

When it happens

Trigger: Running 'gemini extensions disable <name> --scope foo' where 'foo' is not one of the valid SettingScope values. The check compares case-insensitively.

Common situations: Typo in scope name (e.g., 'worckspace'); passing a scope name in an unexpected format; misunderstanding the available scopes.

Related errors

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