{"record":{"id":"2822f87b3fd75a71","repo":"yarnpkg/yarn","slug":"found-incompatible-module","errorCode":null,"errorMessage":"Found incompatible module.","messagePattern":"Found incompatible module\\.","errorType":"exception","errorClass":"MessageError","httpStatus":null,"severity":"error","filePath":"src/package-compatibility.js","lineNumber":160,"sourceCode":"      let name = entry[0];\n      const range = entry[1];\n\n      if (aliases[name]) {\n        name = aliases[name];\n      }\n\n      if (VERSIONS[name]) {\n        if (!testEngine(name, range, VERSIONS, config.looseSemver)) {\n          pushError(reporter.lang('incompatibleEngine', name, range, VERSIONS[name]));\n        }\n      } else if (ignore.indexOf(name) < 0) {\n        reporter.warn(`${human}: ${reporter.lang('invalidEngine', name)}`);\n      }\n    }\n  }\n\n  if (didError) {\n    throw new MessageError(reporter.lang('foundIncompatible'));\n  }\n}\n\nexport function check(infos: Array<Manifest>, config: Config, ignoreEngines: boolean) {\n  for (const info of infos) {\n    checkOne(info, config, ignoreEngines);\n  }\n}\n\nfunction shouldCheckCpu(cpu: $PropertyType<Manifest, 'cpu'>, ignorePlatform: boolean): boolean %checks {\n  return !ignorePlatform && Array.isArray(cpu) && cpu.length > 0;\n}\n\nfunction shouldCheckPlatform(os: $PropertyType<Manifest, 'os'>, ignorePlatform: boolean): boolean %checks {\n  return !ignorePlatform && Array.isArray(os) && os.length > 0;\n}\n\nfunction shouldCheckEngines(engines: $PropertyType<Manifest, 'engines'>, ignoreEngines: boolean): boolean %checks {","sourceCodeStart":142,"sourceCodeEnd":178,"githubUrl":"https://github.com/yarnpkg/yarn/blob/c2dda503f3759b5be5f0e24ecd9cf5c97a540147/src/package-compatibility.js#L142-L178","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Update your Node/Yarn version to satisfy the package's `engines` range (use nvm/corepack).","If you accept the risk, install with `--ignore-engines` (`ignoreEngines` true) or `--ignore-platform`.","Move the package to `optionalDependencies` if it is platform-specific and non-critical.","Pin a version of the dependency that supports your platform/runtime."],"exampleFix":"// before (package.json of dep requires newer node)\n\"engines\": { \"node\": \">=18\" }\n# runtime is Node 16. Fix: upgrade runtime\nnvm install 18\nnvm use 18\nyarn install\n# or bypass (not recommended):\nyarn install --ignore-engines","handlingStrategy":"validation","validationCode":"const semver = require('semver');\nfunction checkEnginesCompat(info, runtimeVersions) {\n  if (!info.engines) return;\n  for (const [name, range] of Object.entries(info.engines)) {\n    if (runtimeVersions[name] && !semver.satisfies(runtimeVersions[name], range)) {\n      throw new Error(`${info.name}@${info.version} requires ${name} ${range} (have ${runtimeVersions[name]})`);\n    }\n  }\n}\ncheckEnginesCompat(info, {node: process.versions.node});","typeGuard":"function isEngineCompatible(info, runtimeVersions, loose) {\n  if (!info.engines) return true;\n  return Object.entries(info.engines).every(([name, range]) =>\n    !runtimeVersions[name] || semver.satisfies(runtimeVersions[name], range, loose ? {loose: true} : {})\n  );\n}","tryCatchPattern":"try {\n  check(infos, config, ignoreEngines);\n} catch (err) {\n  if (err.message.includes('incompatible')) {\n    reporter.error('Use --ignore-engines only if you accept the risk, or upgrade the runtime.');\n    process.exit(1);\n  }\n  throw err;\n}","preventionTips":["Pin Node/Yarn versions (nvm, corepack, engines field) consistently across the team.","Move platform-specific packages to optionalDependencies when possible.","Audit engine ranges during dependency upgrades in CI."],"tags":["engines","platform","compatibility","install"],"backgroundTag":null,"analyzedSha":"c2dda503f3759b5be5f0e24ecd9cf5c97a540147","analyzedAt":"2026-08-13T04:17:06.305Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}