yarnpkg/yarn · error · MessageError

invalidPackageName

Error message

invalidPackageName

What it means

The `yarn create` runner destructures the first positional arg as `builderName` (`create.js:55`). If it is falsy (no args), it throws `invalidPackageName` ('Invalid package name.') before any name coercion or resolution. This is the empty-argument guard for the create command.

Source

Thrown at src/cli/commands/create.js:58

}

export function coerceCreatePackageName(str: string): Object {
  const pkgNameObj = parsePackageName(str);
  const coercedName = pkgNameObj.name !== '' ? `create-${pkgNameObj.name}` : `create`;
  const coercedPkgNameObj = {
    ...pkgNameObj,
    name: coercedName,
    fullName: [pkgNameObj.scope, coercedName].filter(Boolean).join('/'),
    full: [pkgNameObj.scope, coercedName, pkgNameObj.path].filter(Boolean).join('/'),
  };
  return coercedPkgNameObj;
}

export async function run(config: Config, reporter: Reporter, flags: Object, args: Array<string>): Promise<void> {
  const [builderName, ...rest] = args;

  if (!builderName) {
    throw new MessageError(reporter.lang('invalidPackageName'));
  }

  const {fullName: packageName, name: commandName} = coerceCreatePackageName(builderName);

  const linkLoc = path.join(config.linkFolder, commandName);
  if (await fs.exists(linkLoc)) {
    reporter.info(reporter.lang('linkUsing', packageName));
  } else {
    await runGlobal(config, reporter, {}, ['add', packageName]);
  }

  const binFolder = await getBinFolder(config, {});
  const command = path.resolve(binFolder, commandName);
  const env = await makeEnv('create', config.cwd, config);

  await child.spawn(command, rest, {stdio: `inherit`, shell: true, env});
}

View on GitHub (pinned to c2dda503f3)

Solutions

1. Pass a kit name: `yarn create react-app my-app`.
2. In scripts, guard the variable: `yarn create "${KIT:?KIT required}" "$@"`.

Example fix

// before
$ yarn create

// after
$ yarn create react-app my-app

function requireBuilderName(args: string[]): string {
  const [builderName] = args;
  if (!builderName) throw new Error('yarn create requires a kit name, e.g. "react-app"');
  return builderName;
}

function hasBuilderName(args: unknown): args is [string, ...string[]] {
  return Array.isArray(args) && typeof args[0] === 'string' && args[0].length > 0;
}

When it happens

Trigger: `const [builderName, ...rest] = args;` yields `undefined` because `args` is empty — i.e. `yarn create` invoked with no kit name.

Common situations: Running `yarn create` bare, a wrapper script that dropped the kit argument, or a shell quoting bug that consumed the name.

Related errors

• missingAddDependencies
• Name should not start with "/", got "${str}"
• Name should not start with ".", got "${str}"
• Scope should not be empty, got "${str}"
• execMissingCommand

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