{"record":{"id":"c81ac530e727107f","repo":"pnpm/pnpm","slug":"config-conflict-link-workspace-packages-with-globa","errorCode":"CONFIG_CONFLICT_LINK_WORKSPACE_PACKAGES_WITH_GLOBAL","errorMessage":"Configuration conflict. \"link-workspace-packages\" may not be used with \"global\"","messagePattern":"Configuration conflict\\. \"link-workspace-packages\" may not be used with \"global\"","errorType":"error_code","errorClass":"PnpmError","httpStatus":null,"severity":"error","filePath":"pnpm11/config/reader/src/index.ts","lineNumber":438,"sourceCode":"    if (pnpmConfig.bin) {\n      fs.mkdirSync(pnpmConfig.bin, { recursive: true })\n      await checkGlobalBinDir(pnpmConfig.bin, { env, shouldAllowWrite: opts.globalDirShouldAllowWrite })\n    }\n    pnpmConfig.save = true\n    pnpmConfig.allowNew = true\n    pnpmConfig.ignoreCurrentSpecifiers = true\n    pnpmConfig.saveProd = true\n    pnpmConfig.saveDev = false\n    pnpmConfig.saveOptional = false\n    if ((pnpmConfig.hoistPattern != null) && (pnpmConfig.hoistPattern.length > 1 || pnpmConfig.hoistPattern[0] !== '*')) {\n      if (opts.cliOptions['hoist-pattern']) {\n        throw new PnpmError('CONFIG_CONFLICT_HOIST_PATTERN_WITH_GLOBAL',\n          'Configuration conflict. \"hoist-pattern\" may not be used with \"global\"')\n      }\n    }\n    if (pnpmConfig.linkWorkspacePackages) {\n      if (opts.cliOptions['link-workspace-packages']) {\n        throw new PnpmError('CONFIG_CONFLICT_LINK_WORKSPACE_PACKAGES_WITH_GLOBAL',\n          'Configuration conflict. \"link-workspace-packages\" may not be used with \"global\"')\n      }\n      pnpmConfig.linkWorkspacePackages = false\n    }\n    if (pnpmConfig.sharedWorkspaceLockfile) {\n      if (opts.cliOptions['shared-workspace-lockfile']) {\n        throw new PnpmError('CONFIG_CONFLICT_SHARED_WORKSPACE_LOCKFILE_WITH_GLOBAL',\n          'Configuration conflict. \"shared-workspace-lockfile\" may not be used with \"global\"')\n      }\n      pnpmConfig.sharedWorkspaceLockfile = false\n    }\n    if (pnpmConfig.lockfileDir) {\n      if (opts.cliOptions['lockfile-dir']) {\n        throw new PnpmError('CONFIG_CONFLICT_LOCKFILE_DIR_WITH_GLOBAL',\n          'Configuration conflict. \"lockfile-dir\" may not be used with \"global\"')\n      }\n      delete pnpmConfig.lockfileDir\n    }","sourceCodeStart":420,"sourceCodeEnd":456,"githubUrl":"https://github.com/pnpm/pnpm/blob/5b11d3a15b9022a2109cb18ed96a5d652630371f/pnpm11/config/reader/src/index.ts#L420-L456","documentation":"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.","triggerScenarios":"`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.","commonSituations":"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.","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"],"exampleFix":"# before\npnpm add -g vercel --link-workspace-packages\n# after\npnpm add -g vercel","handlingStrategy":"validation","validationCode":"const findGlobalConflicts = (cliOptions: Record<string, unknown>): string[] =>\n  (cliOptions['global'] || cliOptions['g'])\n    ? (['link-workspace-packages', 'hoist-pattern', 'shared-workspace-lockfile', 'lockfile-dir', 'virtual-store-dir'] as const)\n        .filter(f => Boolean(cliOptions[f]))\n    : []\nif (findGlobalConflicts(cliOptions).length > 0) throw new Error('strip workspace flags from global installs')","typeGuard":null,"tryCatchPattern":"try {\n  await runPnpm(args)\n} catch (err) {\n  if (util.types.isNativeError(err) && 'code' in err && err.code === 'CONFIG_CONFLICT_LINK_WORKSPACE_PACKAGES_WITH_GLOBAL') {\n    // drop '--link-workspace-packages' from args and retry once\n  } else throw err\n}","preventionTips":["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"],"tags":["config","cli","global","workspace","conflict"],"backgroundTag":null,"analyzedSha":"5b11d3a15b9022a2109cb18ed96a5d652630371f","analyzedAt":"2026-08-16T13:18:59.198Z","schemaVersion":2},"datasetVersion":"2026-08-16T18:17:16.020Z"}