Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

Build fails because a tool still runs PostCSS 7 and Tailwind needs 8

ErrorError: PostCSS plugin tailwindcss requires PostCSS 8.

Short answer

Tailwind CSS 2 and later depend on PostCSS 8. The error means a tool in your build chain still loads PostCSS 7. Either upgrade that tool to a release that uses PostCSS 8, or, if you cannot yet, install the postcss7-compat build of Tailwind that the Tailwind 2 docs provide for this case.

  • Applies to Tailwind CSS 2 and 3, PostCSS 7 and 8, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    List every copy of PostCSS in the project and which package pulls it in. A 7.x entry under your build tool is the culprit.

    npm ls postcss
  2. 2Match what you see, then jump to its fix

    1. 1npm ls postcss shows postcss@7 below the tool that runs your CSS buildAn old build tool pins PostCSS 7Fix
    2. 2The build tool has no PostCSS 8 release for your setupThe tool cannot be upgraded yet, so PostCSS 7 must stayFix

What does the error look like?

  • Error: PostCSS plugin tailwindcss requires PostCSS 8.

Cause 1 of 2

An old build tool pins PostCSS 7

1Check

Tailwind 2 and later need PostCSS 8. A tool that has not moved to PostCSS 8 loads version 7 and rejects the plugin.

npm ls postcss
npm outdated

2Fix

Upgrade the build tool to a release that supports PostCSS 8. Then use the standard Tailwind setup that matches your Tailwind version; for Tailwind 4 the PostCSS plugin is the separate @tailwindcss/postcss package.

npm install -D postcss@latest
npm install -D @tailwindcss/postcss

3Verify

Only PostCSS 8 or newer is listed, and the build runs.

npm ls postcss
npm run build

Confirmed by tailwindcss.com

Did this fix it?

Cause 2 of 2

The tool cannot be upgraded yet, so PostCSS 7 must stay

1Check

The Tailwind 2 docs publish an identical build for this case, called @tailwindcss/postcss7-compat. It works with PostCSS 7.

npm ls tailwindcss postcss autoprefixer

2Fix

Replace the three packages with the compat build, PostCSS 7 and Autoprefixer 9. Switch back to the standard build when your tools support PostCSS 8.

npm uninstall tailwindcss postcss autoprefixer
npm install -D tailwindcss@npm:@tailwindcss/postcss7-compat postcss@^7 autoprefixer@^9

3Verify

Run the build again.

npm run build

Confirmed by v2.tailwindcss.com

Did this fix it?

How do I stop it coming back?

  • Upgrade build tools, Tailwind and PostCSS together, not one at a time.
  • Treat the compat build as a stopgap and write down the day you plan to remove it.
  • Run npm ls postcss after any upgrade, so a second copy is noticed early.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Web apps

Next.js fails with Cannot find module 'tailwindcss'

Error: Cannot find module 'tailwindcss'

Next.js loads Tailwind through PostCSS, so the error means the package named in postcss.config is not installed where the build runs.

3 causes, each with a fix

Web apps

shadcn/ui setup fails in a Vite React project using Tailwind v4

Imports from @/components/ui do not resolve in the editor or the build

shadcn init needs three things in a Vite project: Tailwind v4 installed with the @tailwindcss/vite plugin and a single @import "tailwindcss" line in your CSS, the @/* path alias in both tsconfig.json and tsconfig.app.json, and the same alias in vite.config.ts, with @types/node installed so path resolves.

4 causes, each with a fix

Web apps

Tailwind build says the dark: class does not exist

dark: utilities work in markup but the build fails where @apply uses them in a separate CSS file

The build error means the CSS file being compiled cannot see your dark variant.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.