What causes "Package manager must be yarn or npm." in gatsbyjs/gatsby?

Use `npm` or `yarn` as the value: `gatsby options set pm npm`.

Package manager must be yarn or npm.

Error message

Package manager must be yarn or npm.

What it means

Thrown by the `gatsby options set` handler when setting the package manager (`pm` or `package-manager` key) to a value other than `yarn` or `npm`. Only those two package managers are supported by `gatsby new`, so any other value is rejected outright.

Source

Thrown at packages/gatsby-cli/src/create-cli.ts:591

            choices: [`pm`, `package-manager`],
            type: `string`,
            describe: `Set the package manager \`gatsby new\` is using.`,
          })
          .positional(`value`, {
            choices: [`npm`, `yarn`],
            type: `string`,
            describe: `Set package manager as \`npm\` or \`yarn\`.`,
          }),

      handler: handlerP(({ cmd, key, value }: yargs.Arguments) => {
        if (!getPackageManager()) {
          setPackageManager(`npm`)
        }

        if (cmd === `set`) {
          if (key === `pm` || key === `package-manager`) {
            if (value && value !== `yarn` && value !== `npm`) {
              report.panic(`Package manager must be yarn or npm.`)
            }

            if (value) {
              // @ts-ignore
              setPackageManager(value)

              return
            } else {
              setPackageManager(`npm`)
            }
          } else {
            reporter.warn(
              `Please pass your desired config key and value. Currently you can only set your package manager using \`pm\`.`
            )
          }
          return
        }

View on GitHub (pinned to 8b06340921)

Solutions

Use `npm` or `yarn` as the value: `gatsby options set pm npm`.
If you use pnpm for the rest of the project, still set Gatsby's option to npm or yarn and manage the install step manually.
Check for trailing whitespace or capitalization in the value.

Example fix

# before
gatsby options set pm pnpm

# after
gatsby options set pm npm

Defensive patterns

Strategy: validation

Validate before calling

const ALLOWED_PM = new Set(['npm', 'yarn'])
if (!ALLOWED_PM.has(String(value))) throw new Error('Package manager must be yarn or npm')

Type guard

const isSupportedPm = (v: unknown): v is 'npm' | 'yarn' => v === 'npm' || v === 'yarn'

Prevention

Only pass `npm` or `yarn` to `gatsby options set pm`.
Avoid trailing whitespace/capitalization in the value.
If you use pnpm elsewhere, still set gatsby's option to npm or yarn.

When it happens

Trigger: Running `gatsby options set pm pnpm` (or any value besides `yarn`/`npm`) triggers the panic. The handler explicitly checks `value !== 'yarn' && value !== 'npm'`.

Common situations: User prefers pnpm but Gatsby's scaffolder only supports npm/yarn; typo in the value (`NPM`, `Yarn`, trailing whitespace); scripting the option with an unsupported pm.

Related errors

AI-assisted analysis of gatsbyjs/gatsby@8b06340921 (2026-08-13). Data as JSON: /api/errors/0ca68097fa288b82. Report an issue: GitHub.