parcel-bundler/parcel · error · ThrowableDiagnostic

Could not install the peer dependency "${name}" for "${modul

Error message

Could not install the peer dependency "${name}" for "${module.name}", installed version ${pkg.version} is incompatible with ${range}

What it means

Thrown by installPeerDependencies() when a module's peer dependency is already installed at a version incompatible with the required range, AND getConflictingLocalDependencies finds conflicts. The function resolves the peer dep's current version, checks semver.satisfies against the peerDependencies range from the module's package.json, and throws if incompatible with a codeframe showing the conflicting package.json entry.

Source

Thrown at packages/core/package-manager/src/installPackage.js:113

    await loadConfig(fs, resolved, ['package.json'], projectRoot),
  ).config;
  const peers = modulePkg.peerDependencies || {};

  let modules: Array<ModuleRequest> = [];
  for (let [name, range] of Object.entries(peers)) {
    invariant(typeof range === 'string');

    let conflicts = await getConflictingLocalDependencies(
      fs,
      name,
      from,
      projectRoot,
    );
    if (conflicts) {
      let {pkg} = await packageManager.resolve(name, from);
      invariant(pkg);
      if (!semver.satisfies(pkg.version, range)) {
        throw new ThrowableDiagnostic({
          diagnostic: {
            message: md`Could not install the peer dependency "${name}" for "${module.name}", installed version ${pkg.version} is incompatible with ${range}`,
            origin: '@parcel/package-manager',
            codeFrames: [
              {
                filePath: conflicts.filePath,
                language: 'json',
                code: conflicts.json,
                codeHighlights: generateJSONCodeHighlights(
                  conflicts.json,
                  conflicts.fields.map(field => ({
                    key: `/${field}/${encodeJSONKeyComponent(name)}`,
                    type: 'key',
                    message: 'Found this conflicting local requirement.',
                  })),
                ),
              },
            ],

View on GitHub (pinned to 59484858a1)

Solutions

Update the conflicting peer dependency in package.json to satisfy the required range: `npm install <peer-name>@<range>`.
Downgrade the module that has the incompatible peer requirement to a version compatible with your current peer dep.
Use npm overrides / yarn resolutions to force the peer dependency to a compatible version.
Check the module's documentation for supported peer dependency versions before installing.

Example fix

// before: installing component-lib needs react@^18, project has react@^17
// Error: Could not install the peer dependency "react" for "component-lib",
// installed version 17.0.2 is incompatible with ^18.0.0

// after: upgrade react
// $ npm install react@^18.0.0 react-dom@^18.0.0

Defensive patterns

Strategy: validation

Validate before calling

// Pre-check peer dependency compatibility before installing
const semver = require('semver');

async function checkPeerCompatibility(packageManager, moduleName, from) {
  // Read the module's package.json for peerDependencies
  let {pkg} = await packageManager.resolve(moduleName, from);
  let peers = pkg.peerDependencies || {};
  for (let [name, range] of Object.entries(peers)) {
    try {
      let {pkg: peerPkg} = await packageManager.resolve(name, from);
      if (peerPkg && !semver.satisfies(peerPkg.version, range)) {
        console.warn(`Peer dep ${name}@${peerPkg.version} incompatible with required ${range}`);
      }
    } catch { /* peer not installed yet */ }
  }
}

Try / catch

try {
  await installPackage(fs, packageManager, [module], from, projectRoot, options);
} catch (e) {
  if (e.diagnostics?.[0]?.message?.includes('peer dependency')) {
    // Extract the incompatible peer dep name and required range
    let msg = e.diagnostics[0].message;
    console.error('Update peer dependency:', msg);
  } else {
    throw e;
  }
}

Prevention

Check a package's peerDependencies before installing it — review its npm page or package.json.
Keep peer dependencies (React, Vue, ESLint, etc.) at versions compatible with your installed libraries.
Use npm overrides / yarn resolutions to align peer dep versions across the dependency tree.
After upgrading a library, verify its peer dep ranges haven't changed.

When it happens

Trigger: installPackage() processes the `peers` object from the module's package.json peerDependencies. For each peer, it calls getConflictingLocalDependencies. If conflicts exist, it resolves the currently installed version and checks semver.satisfies(pkg.version, range). If false, it throws. This means the peer dep is pinned at a wrong version by a local package.json entry.

Common situations: Installing a React component library that peer-depends on react@^18, but the project pins react@^17. Installing ESLint plugins with incompatible ESLint peer ranges. A monorepo where different workspace packages require different peer versions. Upgrading a package whose new version has stricter peer dep ranges than the old one.

Related errors

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