pnpm/pnpm · error · PnpmError

CONFIG_CONFLICT_LINK_WORKSPACE_PACKAGES_WITH_GLOBAL

CONFIG_CONFLICT_LINK_WORKSPACE_PACKAGES_WITH_GLOBAL

Error message

Configuration conflict. "link-workspace-packages" may not be used with "global"

What it means

Global installs have no workspace to link packages from, so link-workspace-packages is incompatible with --global. The reader throws when the effective setting is truthy AND '--link-workspace-packages' was passed explicitly on the CLI; a truthy value originating only from a config file is silently forced to false instead of throwing.

Source

Thrown at pnpm11/config/reader/src/index.ts:438

    if (pnpmConfig.bin) {
      fs.mkdirSync(pnpmConfig.bin, { recursive: true })
      await checkGlobalBinDir(pnpmConfig.bin, { env, shouldAllowWrite: opts.globalDirShouldAllowWrite })
    }
    pnpmConfig.save = true
    pnpmConfig.allowNew = true
    pnpmConfig.ignoreCurrentSpecifiers = true
    pnpmConfig.saveProd = true
    pnpmConfig.saveDev = false
    pnpmConfig.saveOptional = false
    if ((pnpmConfig.hoistPattern != null) && (pnpmConfig.hoistPattern.length > 1 || pnpmConfig.hoistPattern[0] !== '*')) {
      if (opts.cliOptions['hoist-pattern']) {
        throw new PnpmError('CONFIG_CONFLICT_HOIST_PATTERN_WITH_GLOBAL',
          'Configuration conflict. "hoist-pattern" may not be used with "global"')
      }
    }
    if (pnpmConfig.linkWorkspacePackages) {
      if (opts.cliOptions['link-workspace-packages']) {
        throw new PnpmError('CONFIG_CONFLICT_LINK_WORKSPACE_PACKAGES_WITH_GLOBAL',
          'Configuration conflict. "link-workspace-packages" may not be used with "global"')
      }
      pnpmConfig.linkWorkspacePackages = false
    }
    if (pnpmConfig.sharedWorkspaceLockfile) {
      if (opts.cliOptions['shared-workspace-lockfile']) {
        throw new PnpmError('CONFIG_CONFLICT_SHARED_WORKSPACE_LOCKFILE_WITH_GLOBAL',
          'Configuration conflict. "shared-workspace-lockfile" may not be used with "global"')
      }
      pnpmConfig.sharedWorkspaceLockfile = false
    }
    if (pnpmConfig.lockfileDir) {
      if (opts.cliOptions['lockfile-dir']) {
        throw new PnpmError('CONFIG_CONFLICT_LOCKFILE_DIR_WITH_GLOBAL',
          'Configuration conflict. "lockfile-dir" may not be used with "global"')
      }
      delete pnpmConfig.lockfileDir
    }

View on GitHub (pinned to 5b11d3a15b)

Solutions

Remove --link-workspace-packages from the global command
Install without -g if workspace linking is genuinely needed
Leave the setting in the project's config file — pnpm disables it automatically for global installs without erroring

Example fix

# before
pnpm add -g vercel --link-workspace-packages
# after
pnpm add -g vercel

Defensive patterns

Strategy: validation

Validate before calling

const findGlobalConflicts = (cliOptions: Record<string, unknown>): string[] =>
  (cliOptions['global'] || cliOptions['g'])
    ? (['link-workspace-packages', 'hoist-pattern', 'shared-workspace-lockfile', 'lockfile-dir', 'virtual-store-dir'] as const)
        .filter(f => Boolean(cliOptions[f]))
    : []
if (findGlobalConflicts(cliOptions).length > 0) throw new Error('strip workspace flags from global installs')

Try / catch

try {
  await runPnpm(args)
} catch (err) {
  if (util.types.isNativeError(err) && 'code' in err && err.code === 'CONFIG_CONFLICT_LINK_WORKSPACE_PACKAGES_WITH_GLOBAL') {
    // drop '--link-workspace-packages' from args and retry once
  } else throw err
}

Prevention

Don't forward monorepo settings as CLI flags into global installs
Let pnpm auto-disable config-file link-workspace-packages in global mode instead of passing the flag
Maintain distinct install commands for global tools vs workspace packages

When it happens

Trigger: `pnpm add -g <pkg> --link-workspace-packages` while the effective linkWorkspacePackages resolves truthy (e.g. enabled in .npmrc, pnpm-workspace.yaml, or by the flag itself). Programmatically: cliOptions containing `global: true` plus `link-workspace-packages` where pnpmConfig.linkWorkspacePackages is truthy. The default is false, so the flag alone is what makes the setting truthy.

Common situations: Monorepo preset scripts applied to all pnpm commands including global ones; developers copying workspace install lines from project docs and adding -g; tooling that forwards every project .npmrc setting as CLI flags.

Related errors

AI-assisted analysis of pnpm/pnpm@5b11d3a15b (2026-08-16). Data as JSON: /api/errors/c81ac530e727107f. Report an issue: GitHub.