parcel-bundler/parcel · error · Error

npm failed to install modules: ${e.message} - ${stderr.join(

Error message

npm failed to install modules: ${e.message} - ${stderr.join('\n')}

What it means

Thrown by the Npm package installer when the npm install subprocess fails (throws an exception caught in the try/catch). The error message concatenates the caught exception's message and the full stderr output from the npm process. The catch block wraps any error — JSON parse failure of npm output, subprocess crash, or npm's own exit code failure.

Source

Thrown at packages/core/package-manager/src/Npm.js:80

        logger.log({
          origin: '@parcel/package-manager',
          message: `Added ${addedCount} packages via npm`,
        });
      }

      // Since we succeeded, stderr might have useful information not included
      // in the json written to stdout. It's also not necessary to log these as
      // errors as they often aren't.
      for (let message of stderr) {
        if (message.length > 0) {
          logger.log({
            origin: '@parcel/package-manager',
            message,
          });
        }
      }
    } catch (e) {
      throw new Error(
        'npm failed to install modules: ' +
          e.message +
          ' - ' +
          stderr.join('\n'),
      );
    }
  }
}

type NPMResults = {|
  added: Array<{name: string, ...}>,
|};

registerSerializableClass(`${pkg.version}:Npm`, Npm);

View on GitHub (pinned to 59484858a1)

Solutions

1. Read the stderr output in the error message — it contains npm's own diagnostic output.
2. Check network connectivity and registry access: `npm ping` or `npm config get registry`.
3. For private registries, verify authentication: `npm whoami` or check .npmrc.
4. Clear npm cache: `npm cache clean --force` then retry.
5. Check disk space and permissions on the project directory and node_modules.

Example fix

// before: npm install fails with registry error
// Error: npm failed to install modules: ...
// - E404 Not Found - GET https://registry.npmjs.org/nonexistent-pkg

// after: fix the package name or registry
// $ npm config get registry  // verify correct registry
// $ npm install  // retry after fixing package.json

// Pre-flight checks before npm install
const {execSync} = require('child_process');

function preflightNpm() {
  // Check registry connectivity
  try {
    execSync('npm ping', {stdio: 'pipe', timeout: 10000});
  } catch {
    throw new Error('npm registry unreachable — check network and proxy settings');
  }
  // Check disk space
  let {execSync: es} = require('child_process');
  let disk = es('df -k .', {encoding: 'utf8'});
  // ... parse and validate
}

try {
  await npmInstaller.install({modules, saveDev, cwd, packagePath, fs});
} catch (e) {
  if (e.message.startsWith('npm failed to install modules')) {
    // Parse stderr from the error message for specific npm error codes
    let stderr = e.message.split(' - ').slice(1).join(' - ');
    if (stderr.includes('E404')) {
      console.error('Package not found — check name in package.json');
    } else if (stderr.includes('EACCES')) {
      console.error('Permission denied — check npm prefix permissions');
    } else {
      console.error('npm install failed:', stderr);
    }
  } else {
    throw e;
  }
}

When it happens

Trigger: install() is called on the Npm class, which spawns `npm install` as a child process. The child process exits non-zero, or the stdout JSON parsing throws. The catch block captures the exception and re-throws with the concatenated message including stderr lines.

Common situations: npm registry is unreachable or returns errors (network issues, corporate proxy, private registry auth failure). package.json references a non-existent package version. npm has insufficient permissions to write to node_modules. Disk full during install. npm cache corruption requiring `npm cache clean --force`.

Related errors

• Yarn failed to install modules: ${e.message}
• pnpm failed to install modules
• Failed to install ${moduleNames}: ${err.message}
• npmResolve failed: fetching ${name} - ${res.status}
• npmFetch failed: fetching ${tarball} - ${res.status}

AI-assisted analysis of parcel-bundler/parcel@59484858a1 (2026-08-13). Data as JSON: /api/errors/c658a39a3935517a. Report an issue: GitHub.