What causes "Failed to parse arguments" in google-gemini/gemini-cli?

Re-run the command with `DEBUG=1` to capture the upstream yargs error logged just before exit.

Failed to parse arguments

Error message

Failed to parse arguments

What it means

Thrown defensively after `yargsInstance.parse()` when the parsed result fails the `isRecord` type guard (i.e. yargs returned something that is not a plain object). This should not happen under normal yargs behavior — yargs always returns an object — so it guards against a malformed parser, a custom coerce that returns a non-object, or a corrupted yargs plugin chain.

Source

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

        .option('accept-raw-output-risk', {
          type: 'boolean',
          description: 'Suppress the security warning when using --raw-output.',
        }),
    )
    .version(await getVersion()) // This will enable the --version flag based on package.json
    .alias('v', 'version')
    .help()
    .alias('h', 'help')
    .strict()
    .demandCommand(0, 0) // Allow base command to run with no subcommands
    .exitProcess(false);

  yargsInstance.wrap(yargsInstance.terminalWidth());
  let result;
  try {
    const parsed = await yargsInstance.parse();
    if (!isRecord(parsed)) {
      throw new Error('Failed to parse arguments');
    }
    result = parsed;
    if (result['skip-trust']) {
      process.env['GEMINI_CLI_TRUST_WORKSPACE'] = 'true';
    }
  } catch (e) {
    const msg = getErrorMessage(e);
    debugLogger.error(msg);
    yargsInstance.showHelp();
    await runExitCleanup();
    process.exit(1);
  }

  // Handle help and version flags manually since we disabled exitProcess
  if (result['help'] || result['version']) {
    await runExitCleanup();
    process.exit(0);
  }

View on GitHub (pinned to 5024443c72)

Solutions

Re-run the command with `DEBUG=1` to capture the upstream yargs error logged just before exit.
Check for custom yargs plugins or coerce functions that may return non-object values.
Pin or upgrade the `yargs` dependency to a known-good version.

Defensive patterns

Strategy: try-catch

Type guard

import { isRecord } from '<core utils>';
function isParsedArgs(v: unknown): v is Record<string, unknown> {
  return isRecord(v);
}

Try / catch

try {
  const parsed = await yargsInstance.parse();
  if (!isRecord(parsed)) throw new Error('Failed to parse arguments');
  // ...
} catch (e) {
  debugLogger.error(getErrorMessage(e));
  yargsInstance.showHelp();
  await runExitCleanup();
  process.exit(1);
}

Prevention

Pin `yargs` to a tested version range.
Audit any custom `coerce` functions to ensure they return primitives or plain objects.
Run smoke tests after upgrading yargs.

When it happens

Trigger: A `coerce` function on some option returning a non-object value that propagates; a yargs version regression where `parse()` returns undefined; corrupted argv state from an upstream middleware.

Common situations: After upgrading yargs to a version with a breaking change; after registering a custom coerce that throws silently; in test harnesses that mock yargs incorrectly; extremely unlikely in normal use.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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