facebook/docusaurus · error · Error

Invalid package manager choice ${packageManager}. Must be on

Error message

Invalid package manager choice ${packageManager}. Must be one of ${PackageManagers.join(', ')}

What it means

Thrown by getPackageManager() in create-docusaurus when the --package-manager CLI option is set to a value that is not one of the supported keys: npm, yarn, pnpm, bun (the keys of LockfileNames in packages/create-docusaurus/src/constants.ts). The check exists because the CLI flag is a raw string from argv and TypeScript cannot enforce the PackageManager union at runtime. Docusaurus needs a known manager so it can later compute the install command and lockfile name.

Source

Thrown at packages/create-docusaurus/src/index.ts:115

          message: 'Select a package manager...',
          choices,
        },
        {
          onCancel() {
            logger.info`Falling back to name=${DefaultPackageManager}`;
          },
        },
      )) as {packageManager?: PackageManager}
    ).packageManager ?? DefaultPackageManager
  );
}

async function getPackageManager(
  dest: string,
  {packageManager, skipInstall}: CLIOptions,
): Promise<PackageManager> {
  if (packageManager && !PackageManagers.includes(packageManager)) {
    throw new Error(
      `Invalid package manager choice ${packageManager}. Must be one of ${PackageManagers.join(
        ', ',
      )}`,
    );
  }

  return (
    // If dest already contains a lockfile (e.g. if using a local template), we
    // always use that instead
    (await findPackageManagerFromLockFile(dest)) ??
    packageManager ??
    (await findPackageManagerFromLockFile('.')) ??
    findPackageManagerFromUserAgent() ??
    // This only happens if the user has a global installation in PATH
    (skipInstall ? DefaultPackageManager : await askForPackageManagerChoice())
  );
}

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Re-run with one of the supported values: --package-manager npm | yarn | pnpm | bun.
2. Omit the flag entirely and let create-docusaurus detect the manager from a lockfile in the dest or cwd, or from the npm_config_user_agent env var.
3. If you need a manager outside the supported set, edit packages/create-docusaurus/src/constants.ts LockfileNames and PackageManagers (maintainer only).

Example fix

# before
npx create-docusaurus my-site --package-manager pnpm2
# after
npx create-docusaurus my-site --package-manager pnpm

import {PackageManagers, type PackageManager} from './constants.js';
function assertPackageManager(pm: string): asserts pm is PackageManager {
  if (!PackageManagers.includes(pm as PackageManager)) {
    throw new Error(
      `Invalid package manager choice ${pm}. Must be one of ${PackageManagers.join(', ')}`,
    );
  }
}
assertPackageManager(argv.packageManager);

import {PackageManagers, type PackageManager} from './constants.js';
const isPackageManager = (v: unknown): v is PackageManager =>
  typeof v === 'string' && (PackageManagers as string[]).includes(v);

When it happens

Trigger: Running create-docusaurus with --package-manager pnpm2, --package-manager npm@9, --package-manager chocolatey, or any typo like --package-manager yrn. Reached in the main init flow the first time getPackageManager validates the CLIOptions.

Common situations: Typos in the flag value; passing a version-qualified manager name (npm@10) instead of just npm; passing a manager that exists on the machine but is not in the supported set (e.g. volta); shell completion or a script feeding an unexpected value.

Related errors

• Directory already exists at path=${dest}!
• Invalid command: ${command}
• Heading ids can either be overwritten or migrated, not both
• Invalid --syntax value "${options.syntax}". Valid values: ${
• Options --overwrite and --migrate cannot be used together.\n

AI-assisted analysis of facebook/docusaurus@3f483e80e3 (2026-08-12). Data as JSON: /api/errors/660929acbe437eac. Report an issue: GitHub.