yarnpkg/yarn · error · MessageError

invalidVersionArgument

Error message

invalidVersionArgument

What it means

Thrown by 'yarn version' when positional args are present but the --new-version flag is not set. In this command, positional args are only meaningful alongside an explicit --new-version value; passing bare args is treated as a misuse.

Source

Thrown at src/cli/commands/version.js:59

export async function setVersion(
  config: Config,
  reporter: Reporter,
  flags: Object,
  args: Array<string>,
  required: boolean,
): Promise<() => Promise<void>> {
  const pkg = await config.readRootManifest();
  const pkgLoc = pkg._loc;
  const scripts = map();
  let newVersion = flags.newVersion;
  let identifier = undefined;
  if (flags.preid) {
    identifier = flags.preid;
  }
  invariant(pkgLoc, 'expected package location');

  if (args.length && !newVersion) {
    throw new MessageError(reporter.lang('invalidVersionArgument', NEW_VERSION_FLAG));
  }

  function runLifecycle(lifecycle: string): Promise<void> {
    if (scripts[lifecycle]) {
      return execCommand({stage: lifecycle, config, cmd: scripts[lifecycle], cwd: config.cwd, isInteractive: true});
    }

    return Promise.resolve();
  }

  function isCommitHooksDisabled(): boolean {
    return flags.commitHooks === false || config.getOption('version-commit-hooks') === false;
  }

  if (pkg.scripts) {
    // inherit `scripts` from manifest
    Object.assign(scripts, pkg.scripts);
  }

View on GitHub (pinned to c2dda503f3)

Solutions

1. Use the bump flags: 'yarn version --patch' (or --minor/--major/--prepatch/--preminor/--premajor).
2. Set an explicit version: 'yarn version --new-version 1.2.3'.
3. Remove any stray positional arguments.

Example fix

# before
$ yarn version patch
# after
$ yarn version --patch

if (args.length > 0 && !flags.newVersion) {
  throw new Error("Positional args are only valid with '--new-version <value>'; use bump flags like --patch instead.");
}

function argsAlignWithFlags(args: string[], flags: Object): boolean {
  return args.length === 0 || Boolean(flags.newVersion);
}

When it happens

Trigger: Running 'yarn version <something>' (any positional arg) without '--new-version <value>', triggering the (args.length && !newVersion) guard.

Common situations: User assumes 'yarn version patch' or 'yarn version 1.2.3' works like other tools; confusion between bump flags (--patch/--minor/--major) and positional input.

Related errors

• requiredVersionInRange
• invalidVersion
• invalidPackageName
• tooFewArguments
• noArguments

AI-assisted analysis of yarnpkg/yarn@c2dda503f3 (2026-08-13). Data as JSON: /api/errors/c72100cb6914e134. Report an issue: GitHub.