{"record":{"id":"cb535421cca59ac5","repo":"pnpm/pnpm","slug":"failed-to-clean-up-replaced-global-installs","errorCode":null,"errorMessage":"Failed to clean up replaced global installs","messagePattern":"Failed to clean up replaced global installs","errorType":"exception","errorClass":"AggregateError","httpStatus":null,"severity":"error","filePath":"pnpm11/global/commands/src/globalActivation.ts","lineNumber":98,"sourceCode":"    // Activation is already committed, so a leftover backup directory\n    // must not fail the command — but it points at a filesystem problem\n    // worth surfacing.\n    globalWarn(`Failed to remove the global bin backup directory at ${prepared.backupDir}: ${getErrorMessage(err)}`)\n  }\n  return prepared.actualBinNames\n}\n\nexport async function cleanupReplacedGlobalInstalls (\n  opts: CleanupReplacedGlobalInstallsOptions\n): Promise<void> {\n  const errors: unknown[] = []\n  for (const group of opts.groups) {\n    // eslint-disable-next-line no-await-in-loop -- Cleanup mutations must settle before the next group starts.\n    errors.push(...await cleanupReplacedGlobalInstall(opts, group))\n  }\n  if (errors.length === 1) throw errors[0]\n  if (errors.length > 1) {\n    throw new AggregateError(errors, 'Failed to clean up replaced global installs')\n  }\n}\n\n// Activation already succeeded when this runs, so every removal is\n// attempted even after one fails; the failures are aggregated instead of\n// aborting the remaining cleanup.\nasync function cleanupReplacedGlobalInstall (\n  opts: CleanupReplacedGlobalInstallsOptions,\n  groupSnapshot: GlobalPackageBinSnapshot\n): Promise<unknown[]> {\n  const errors: unknown[] = []\n  const { info: group, binNames } = groupSnapshot\n  let binRemovalFailed = false\n  for (const binName of binNames) {\n    if (opts.activatedBins.has(binName) || opts.protectedBins.has(binName)) continue\n    try {\n      await removeBin(path.join(opts.globalBinDir, binName)) // eslint-disable-line no-await-in-loop -- Each removal must settle before cleanup continues.\n    } catch (err) {","sourceCodeStart":80,"sourceCodeEnd":116,"githubUrl":"https://github.com/pnpm/pnpm/blob/e45f0332229b094d61f2ecad114a166e338c0d61/pnpm11/global/commands/src/globalActivation.ts#L80-L116","documentation":"This `AggregateError` is thrown by `cleanupReplacedGlobalInstalls` after a successful activation when removing the bins and install directories of the previously replaced global package group(s) failed. Activation is already committed, so every removal is attempted and individual failures are collected; if two or more failures accumulate, they are aggregated under this message (a single failure is rethrown as-is). The new install works, but stale shims or old install directories remain on disk.","triggerScenarios":"Thrown when, for at least two distinct items across `opts.groups`: `removeBin(globalBinDir/<binName>)` rejects for a non-activated, non-protected bin name, the group's old hash-link `rm` fails, or the group's old `installDir` recursive `rm` fails — and the group whose bin removal failed is intentionally kept until all its bins are gone.","commonSituations":"A bin shim still held open or locked by a running program or antivirus (EPERM/EBUSY on Windows); a read-only or root-owned global bin dir after a sudo/non-sudo mix; an old install directory containing files created by a different user or mounted volume; a stale snapshot in the global packages state referencing bins that were manually edited.","solutions":["Read the aggregated `errors` array for the concrete per-path failures (EPERM/ENOENT/etc.) and address each.","Close programs or exclusions holding the stale shims, or delete the listed leftovers manually, then rerun the command to let cleanup complete.","Fix ownership/permissions of the global bin dir and global dir (`chown`/`chmod`, avoid mixing sudo and non-sudo installs).","Manually remove stale shims in the global bin dir and the old group install dir printed in the error, since activation has already succeeded.","If a stale snapshot references bins that no longer exist, clean the global state entry for that group."],"exampleFix":"// before: leftover shim locked by a running watcher\n$ pnpm add -g eslint\nAggregateError: Failed to clean up replaced global installs\n// after\n$ rm -f \"$(pnpm config get global-bin-dir)/eslint\"  # after stopping the watcher\n$ pnpm add -g eslint","handlingStrategy":"try-catch","validationCode":"// Before activating over an old group, verify its shims and install dir are removable\nimport fs from 'node:fs'\nasync function isRemovable (p: string): Promise<boolean> {\n  try { await fs.promises.access(p, fs.constants.W_OK) } catch { return false }\n  return true\n}","typeGuard":"import util from 'node:util'\nfunction isCleanupAggregateError (err: unknown): err is AggregateError {\n  return util.types.isNativeError(err) && err instanceof AggregateError &&\n    err.message === 'Failed to clean up replaced global installs'\n}","tryCatchPattern":"try {\n  await cleanupReplacedGlobalInstalls(opts)\n} catch (err) {\n  if (isCleanupAggregateError(err)) {\n    for (const e of err.errors) {\n      // Log each per-path failure (EPERM/ENOENT/...); activation already succeeded,\n      // so only schedule manual cleanup of the named leftovers.\n    }\n  } else {\n    throw err\n  }\n}","preventionTips":["Treat cleanup failures as non-fatal: activation succeeded, so warn and schedule manual removal instead of retrying the whole install.","Keep global bin and global dir permissions consistent for the user running pnpm.","On Windows, stop tools that execute or scan stale shims before updating global packages.","Periodically reconcile the global packages state so snapshots do not reference bins deleted out-of-band."],"tags":["global-install","cleanup","filesystem","aggregate-error"],"backgroundTag":"file-write-failed","analyzedSha":"e45f0332229b094d61f2ecad114a166e338c0d61","analyzedAt":"2026-09-22T05:07:20.233Z","contentChangedAt":"2026-09-22T05:07:20.233Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}