{"record":{"id":"99ebf11a5fdfc8fd","repo":"parcel-bundler/parcel","slug":"the-plugin-pluginname-is-not-compatible-with","errorCode":null,"errorMessage":"The plugin \"${pluginName}\" is not compatible with the current version of Parcel. Requires \"${parcelVersionRange}\" but the current version is \"${PARCEL_VERSION}\".","messagePattern":"The plugin \"(.+?)\" is not compatible with the current version of Parcel\\. Requires \"(.+?)\" but the current version is \"(.+?)\"\\.","errorType":"exception","errorClass":"ThrowableDiagnostic","httpStatus":null,"severity":"error","filePath":"packages/core/core/src/loadParcelPlugin.js","lineNumber":205,"sourceCode":"          origin: '@parcel/core',\n          message: `The plugin \"${pluginName}\" needs to specify a \\`package.json#engines.parcel\\` field with the supported Parcel version range.`,\n        });\n      }\n\n      if (\n        parcelVersionRange &&\n        !semver.satisfies(PARCEL_VERSION, parcelVersionRange)\n      ) {\n        let pkgFile = nullthrows(\n          await resolveConfig(\n            options.inputFS,\n            resolved,\n            ['package.json'],\n            options.projectRoot,\n          ),\n        );\n        let pkgContents = await options.inputFS.readFile(pkgFile, 'utf8');\n        throw new ThrowableDiagnostic({\n          diagnostic: {\n            message: md`The plugin \"${pluginName}\" is not compatible with the current version of Parcel. Requires \"${parcelVersionRange}\" but the current version is \"${PARCEL_VERSION}\".`,\n            origin: '@parcel/core',\n            codeFrames: [\n              {\n                filePath: pkgFile,\n                language: 'json5',\n                code: pkgContents,\n                codeHighlights: generateJSONCodeHighlights(pkgContents, [\n                  {\n                    key: '/engines/parcel',\n                  },\n                ]),\n              },\n            ],\n          },\n        });\n      }","sourceCodeStart":187,"sourceCodeEnd":223,"githubUrl":"https://github.com/parcel-bundler/parcel/blob/59484858a1a0bcbb71f74088956bb437a2db6505/packages/core/core/src/loadParcelPlugin.js#L187-L223","documentation":"A plugin's `package.json` may declare an `engines.parcel` semver range declaring which Parcel versions it supports. After resolving the plugin, Parcel checks `semver.satisfies(PARCEL_VERSION, parcelVersionRange)`; if the running Parcel version falls outside the range, it throws with both the required range and the current version, plus a code frame on the plugin's package.json.","triggerScenarios":"A plugin whose `engines.parcel` range excludes the installed Parcel version (e.g. plugin requires `^2.0.0` but Parcel is `2.9.0` and the range is actually narrower, or a v1 plugin on Parcel v2).","commonSituations":"Upgrading Parcel without updating plugins; using a plugin pinned to an older major; mismatched versions across a monorepo.","solutions":["Update the plugin to a version whose `engines.parcel` covers your Parcel version.","Pin Parcel to a version the plugin supports.","If you own the plugin, widen or update its `engines.parcel` range and republish."],"exampleFix":"// before (plugin package.json)\n{ \"engines\": { \"parcel\": \"2.0.0 - 2.5.0\" } }\n\n// after\n{ \"engines\": { \"parcel\": \"^2.0.0\" } }","handlingStrategy":"validation","validationCode":"// Check semver compatibility before loading the plugin.\nimport semver from 'semver';\nconst range = pluginPkg.engines?.parcel;\nif (range && !semver.satisfies(PARCEL_VERSION, range)) {\n  throw new Error(`upgrade/downgrade plugin to satisfy ${range}`);\n}","typeGuard":"function satisfiesParcel(pluginPkg: any, parcelVersion: string): boolean {\n  const range = pluginPkg.engines?.parcel;\n  return !range || semver.satisfies(parcelVersion, range);\n}","tryCatchPattern":null,"preventionTips":["Keep Parcel and plugins on compatible majors.","When upgrading Parcel, run a compatibility check on plugin engines.parcel.","Lock plugin versions in CI to avoid drift."],"tags":["plugin","versioning","semver","compatibility"],"backgroundTag":null,"analyzedSha":"59484858a1a0bcbb71f74088956bb437a2db6505","analyzedAt":"2026-08-13T04:06:35.925Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}