Failed to uninstall "${packageToUninstall}". Please uninstal

Error message

Failed to uninstall "${packageToUninstall}". Please uninstall it manually.

What it means

Thrown by the `uninstallPackage` function in next-codemod when the underlying package manager subprocess (npm/pnpm/yarn/bun) exits with a non-zero status. The codemod runs `<pkgManager> <uninstall|remove> <package>` via execa.sync and catches the failure, re-throwing with a user-friendly message that asks you to finish the uninstall manually.

Source

Thrown at packages/next-codemod/lib/handle-package.ts:119

export function uninstallPackage(
  packageToUninstall: string,
  pkgManager?: PackageManager
) {
  pkgManager ??= getPkgManager(process.cwd())
  if (!pkgManager) throw new Error('Failed to find package manager')

  let command = 'uninstall'
  if (pkgManager === 'yarn') {
    command = 'remove'
  }

  try {
    execa.sync(pkgManager, [command, packageToUninstall], {
      stdio: 'inherit',
      shell: true,
    })
  } catch (error) {
    throw new Error(
      `Failed to uninstall "${packageToUninstall}". Please uninstall it manually.`,
      { cause: error }
    )
  }
}

const ADD_CMD_FLAG = {
  npm: 'install',
  yarn: 'add',
  pnpm: 'add',
  bun: 'add',
}

const DEV_DEP_FLAG = {
  npm: '--save-dev',
  yarn: '--dev',
  pnpm: '--save-dev',
  bun: '--dev',

View on GitHub (pinned to 0ae8c72462)

Solutions

Run the uninstall command manually to see the real error: `npm uninstall <package>` (or `pnpm remove`, `yarn remove`, `bun remove`).
Ensure only one package manager lock file exists (delete stale lock files and node_modules, then reinstall).
Check that the package manager binary is installed and on your PATH (`<pkgManager> --version`).
Retry the codemod after resolving the underlying package manager error.

Example fix

// The codemod calls this internally:
uninstallPackage('eslint-config-next')

// If it fails, run the equivalent manually:
// pnpm remove eslint-config-next

Defensive patterns

Strategy: try-catch

Validate before calling

// Before calling uninstallPackage, verify the package is installed
import { readFileSync } from 'fs'
function isPackageInstalled(name: string, cwd = process.cwd()): boolean {
  try {
    const pkg = JSON.parse(readFileSync(`${cwd}/package.json`, 'utf8'))
    return Boolean(pkg.dependencies?.[name] || pkg.devDependencies?.[name])
  } catch { return false }
}

Try / catch

try {
  uninstallPackage(packageToUninstall)
} catch (e) {
  // The cause holds the original execa error with stderr
  console.error('Manual uninstall needed:', e.message)
  if (e.cause) console.error('Underlying error:', e.cause.shortMessage ?? e.cause)
}

Prevention

Ensure the package manager binary is on PATH and functional before running codemods.
Keep only one lock file in the project to avoid package manager confusion.
Run codemods with network access available, or pre-install the affected packages.

When it happens

Trigger: Any next-codemod migration that calls `uninstallPackage` (e.g., removing a deprecated package during an upgrade codemod) and the spawned package manager command fails. The original subprocess error is attached as `cause`.

Common situations: The target package is already not installed; network or registry errors (timeout, 5xx); file permission errors (EACCES on node_modules); corrupted or locked node_modules; conflicting package manager lock files (e.g., both package-lock.json and pnpm-lock.yaml); running the codemod offline.

Related errors

AI-assisted analysis of vercel/next.js@0ae8c72462 (2026-08-06). Data as JSON: /api/errors/9a74ea33165f1412. Report an issue: GitHub.