Failed to install "${packageToInstall}". Please install it m

Error message

Failed to install "${packageToInstall}". Please install it manually.

What it means

Thrown by `installPackages` in next-codemod when `execa.sync` running `<pkgManager> <install|add> <packages...>` exits non-zero. The original error is preserved as `cause`. The codemod gives up and asks you to install the package manually.

Source

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

  } = options

  if (!packageManager) throw new Error('Failed to find package manager')

  const addCmd = ADD_CMD_FLAG[packageManager]
  const devDepFlag = dev ? DEV_DEP_FLAG[packageManager] : undefined

  const installFlags = [addCmd]
  if (devDepFlag) {
    installFlags.push(devDepFlag)
  }
  try {
    execa.sync(packageManager, [...installFlags, ...packageToInstall], {
      // Keeping stderr since it'll likely be relevant later when it fails.
      stdio: silent ? ['ignore', 'ignore', 'inherit'] : 'inherit',
      shell: true,
    })
  } catch (error) {
    throw new Error(
      `Failed to install "${packageToInstall}". Please install it manually.`,
      { cause: error }
    )
  }
}

export function runInstallation(
  packageManager: PackageManager,
  options: { cwd: string }
) {
  try {
    execa.sync(packageManager, ['install'], {
      cwd: options.cwd,
      env: {
        ...process.env,
        // In case NODE_ENV=production is set, we still want dev dependencies to
        // be installed. Otherwise we won't be able to check for peer dependencies.
        // --production=false is not implemented by every package manager.

View on GitHub (pinned to 0ae8c72462)

Solutions

Run the install command manually to see the full error: `npm install <package>` (or `pnpm add`, `yarn add`, `bun add`).
Clear the package manager cache (`npm cache clean --force`, `pnpm store prune`) and retry.
Check for peer dependency conflicts and resolve them before re-running the codemod.
Verify network/proxy connectivity to the npm registry.

Example fix

// The codemod runs this internally and fails:
installPackages(['eslint', '@eslint/js'])

// Run the equivalent manually:
// pnpm add eslint @eslint/js

Defensive patterns

Strategy: try-catch

Validate before calling

// Verify network/registry connectivity before installing
import { execSync } from 'child_process'
function canReachRegistry(): boolean {
  try { execSync('npm ping', { stdio: 'ignore' }); return true } catch { return false }
}

Try / catch

try {
  installPackages(['next'], { packageManager: 'npm' })
} catch (e) {
  console.error(e.message) // Failed to install ...
  // e.cause has the execa error with exit code and stderr
  process.exit(1)
}

Prevention

Verify registry connectivity before running codemods that install packages.
Resolve peer dependency conflicts in package.json beforehand.
Ensure sufficient disk space and write permissions on node_modules.

When it happens

Trigger: Any next-codemod that installs new packages (e.g., adding eslint dependencies during the next-lint-to-eslint-cli migration) when the package manager add/install subprocess fails.

Common situations: Network or registry connectivity issues; package version conflicts or unresolvable peer deps; disk space or permission errors; running behind a corporate proxy that blocks the registry; corrupted package manager cache.

Related errors

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