parcel-bundler/parcel · error · ThrowableDiagnostic

Could not resolve package "${name}" that satisfies ${range}.

Error message

Could not resolve package "${name}" that satisfies ${range}. Found ${version}.

What it means

Thrown by NodePackageManager.resolve() when a module is resolved but its version doesn't satisfy the requested range, AND there are NO local dependency conflicts to report (conflicts==null or the conflict branch wasn't taken). This is the fallback throw at the end of the version-check block. The hint suggests the incompatible version was installed transitively. Includes the found version number if available.

Source

Thrown at packages/core/package-manager/src/NodePackageManager.js:409

                      conflicts.fields.map(field => ({
                        key: `/${field}/${encodeJSONKeyComponent(name)}`,
                        type: 'key',
                        message: 'Found this conflicting local requirement.',
                      })),
                    ),
                  },
                ],
              },
            });
          }

          let version = pkg?.version;
          let message = md`Could not resolve package "${name}" that satisfies ${range}.`;
          if (version != null) {
            message += md` Found ${version}.`;
          }

          throw new ThrowableDiagnostic({
            diagnostic: {
              message,
              hints: [
                'Looks like the incompatible version was installed transitively. Add this package as a direct dependency with a compatible version range.',
              ],
            },
          });
        }
      }

      cache.set(key, resolved);
      invalidationsCache.clear();

      // Add the specifier as a child to the parent module.
      // Don't do this if the specifier was an absolute path, as this was likely a dynamically resolved path
      // (e.g. babel uses require() to load .babelrc.js configs and we don't want them to be added  as children of babel itself).
      if (!path.isAbsolute(name)) {
        let moduleChildren = children.get(from);

View on GitHub (pinned to 59484858a1)

Solutions

Add the package as a direct dependency in package.json with the required version range: `npm install <name>@<range>`.
Use npm overrides or yarn resolutions to force the correct version for transitive dependencies.
Audit the dependency tree with `npm ls <name>` to find which package pulls in the incompatible version.
Update the package that requires the incompatible transitive dependency to a newer version.

Example fix

// before: transitive dep installs wrong version
// parcel plugin needs core-js@^3, but node_modules has core-js@2.x

// after: add as direct dependency
// $ npm install core-js@^3.0.0

Defensive patterns

Strategy: validation

Validate before calling

// Pre-check: verify installed version satisfies required range
const semver = require('semver');
const path = require('path');

function checkInstalledVersion(name, range, projectRoot) {
  try {
    let pkgPath = require.resolve(path.join(name, 'package.json'), {
      paths: [projectRoot],
    });
    let pkg = require(pkgPath);
    if (!semver.satisfies(pkg.version, range)) {
      return {ok: false, found: pkg.version, required: range};
    }
    return {ok: true};
  } catch {
    return {ok: false, error: 'not installed'};
  }
}

Try / catch

try {
  let resolved = await packageManager.resolve(id, from, {range});
} catch (e) {
  if (e.diagnostics?.[0]?.message?.includes('Could not resolve package')) {
    // Incompatible transitive version — add as direct dependency
    console.error(`npm install ${name}@"${range}"`);
  } else {
    throw e;
  }
}

Prevention

Add packages with strict version requirements as direct dependencies rather than relying on transitive installation.
Use npm overrides or yarn resolutions to pin transitive dependencies to compatible versions.
Run `npm ls <name>` to trace where incompatible versions come from.
Lock down dependency versions with a lockfile and commit it.

When it happens

Trigger: resolve() is called with a `range` option. The resolved package exists but semver.satisfies(pkg.version, range) returns false. No conflicting local dependencies are found (conflicts==null), so the code falls through past the auto-install and conflict branches to this throw. The package was likely pulled in by a transitive dependency at a different version.

Common situations: A Parcel plugin requires a specific version of a utility (e.g., core-js@3) but a transitive dependency installed core-js@2. The project doesn't directly list the conflicting package. npm's flat hoisting placed an older version at the top of node_modules.

Related errors

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