Node.js "PostCSS plugin requires PostCSS 8" (peer) in CI

A PostCSS plugin built for the PostCSS 8 API was loaded against a PostCSS 7 instance in the dependency tree. The version mismatch makes the plugin refuse to load and the build fails.

What this error means

A build fails while loading a PostCSS plugin with a message that it requires PostCSS 8 (or a peer warning escalated). Two PostCSS versions are present in node_modules.

node

Error: Loading PostCSS Plugin failed: postcss-preset-env requires
PostCSS 8.
Migration guide for end-users:
https://github.com/postcss/postcss/wiki/PostCSS-8-for-end-users

Common causes

Mixed PostCSS 7 and 8 in the tree

An older tool pins PostCSS 7 while a plugin needs 8. Both get installed and the plugin loads against the wrong major.

How to fix it

Align everything on PostCSS 8

Upgrade the tooling and plugins so a single PostCSS 8 resolves across the tree.

Upgrade the bundler/framework that pins PostCSS 7.
Install postcss@8 and PostCSS-8-compatible plugin versions.
Run npm ls postcss to confirm a single version.

Terminal

npm install -D postcss@8
npm ls postcss

Dedupe or override the PostCSS version

Force a single PostCSS version with an override when a transitive dep pins the old major.

package.json

{
  "overrides": { "postcss": "^8" }
}

How to prevent it

Keep PostCSS and its plugins on the same major.
Run npm ls postcss after dependency changes to catch duplicates.
Use overrides to pin a single PostCSS when transitive deps disagree.