yarnpkg/yarn · error · MessageError

Found incompatible module.

Error message

Found incompatible module.

What it means

Thrown by `checkOne` in package-compatibility when a NON-optional dependency fails platform (os/cpu) or engine (node/yarn version) checks. Optional deps that fail are silently marked `ignore`+`incompatible`; a hard failure on a required package sets `didError` and this `foundIncompatible` MessageError propagates, halting the install.

Source

Thrown at src/package-compatibility.js:160

      let name = entry[0];
      const range = entry[1];

      if (aliases[name]) {
        name = aliases[name];
      }

      if (VERSIONS[name]) {
        if (!testEngine(name, range, VERSIONS, config.looseSemver)) {
          pushError(reporter.lang('incompatibleEngine', name, range, VERSIONS[name]));
        }
      } else if (ignore.indexOf(name) < 0) {
        reporter.warn(`${human}: ${reporter.lang('invalidEngine', name)}`);
      }
    }
  }

  if (didError) {
    throw new MessageError(reporter.lang('foundIncompatible'));
  }
}

export function check(infos: Array<Manifest>, config: Config, ignoreEngines: boolean) {
  for (const info of infos) {
    checkOne(info, config, ignoreEngines);
  }
}

function shouldCheckCpu(cpu: $PropertyType<Manifest, 'cpu'>, ignorePlatform: boolean): boolean %checks {
  return !ignorePlatform && Array.isArray(cpu) && cpu.length > 0;
}

function shouldCheckPlatform(os: $PropertyType<Manifest, 'os'>, ignorePlatform: boolean): boolean %checks {
  return !ignorePlatform && Array.isArray(os) && os.length > 0;
}

function shouldCheckEngines(engines: $PropertyType<Manifest, 'engines'>, ignoreEngines: boolean): boolean %checks {

View on GitHub (pinned to c2dda503f3)

Solutions

1. Update your Node/Yarn version to satisfy the package's `engines` range (use nvm/corepack).
2. If you accept the risk, install with `--ignore-engines` (`ignoreEngines` true) or `--ignore-platform`.
3. Move the package to `optionalDependencies` if it is platform-specific and non-critical.
4. Pin a version of the dependency that supports your platform/runtime.

Example fix

// before (package.json of dep requires newer node)
"engines": { "node": ">=18" }
# runtime is Node 16. Fix: upgrade runtime
nvm install 18
nvm use 18
yarn install
# or bypass (not recommended):
yarn install --ignore-engines

const semver = require('semver');
function checkEnginesCompat(info, runtimeVersions) {
  if (!info.engines) return;
  for (const [name, range] of Object.entries(info.engines)) {
    if (runtimeVersions[name] && !semver.satisfies(runtimeVersions[name], range)) {
      throw new Error(`${info.name}@${info.version} requires ${name} ${range} (have ${runtimeVersions[name]})`);
    }
  }
}
checkEnginesCompat(info, {node: process.versions.node});

function isEngineCompatible(info, runtimeVersions, loose) {
  if (!info.engines) return true;
  return Object.entries(info.engines).every(([name, range]) =>
    !runtimeVersions[name] || semver.satisfies(runtimeVersions[name], range, loose ? {loose: true} : {})
  );
}

try {
  check(infos, config, ignoreEngines);
} catch (err) {
  if (err.message.includes('incompatible')) {
    reporter.error('Use --ignore-engines only if you accept the risk, or upgrade the runtime.');
    process.exit(1);
  }
  throw err;
}

When it happens

Trigger: Installing a package whose `os` array excludes the current platform, whose `cpu` array excludes the current arch, or whose `engines.node`/`engines.yarn` range does not match the running versions — and the package is not marked optional.

Common situations: Installing a native/OS-specific package (e.g. node-fsevents on Linux, a Windows-only tool on macOS). A package declares `engines.node >= 18` but the runtime is Node 16. Upgrading the runtime without checking declared engine ranges.

Related errors

• frozenLockfileError
• installCommandRenamed
• noRequiredLockfile
• This command can only be run inside an individual workspace.
• ENOENT

AI-assisted analysis of yarnpkg/yarn@c2dda503f3 (2026-08-13). Data as JSON: /api/errors/2822f87b3fd75a71. Report an issue: GitHub.