Tailwind CSS 4 build fails on @apply in a Next.js project
Cannot apply unknown utility classShort answer
Tailwind 4 only knows its utilities in a stylesheet that imports Tailwind. If @apply sits in a CSS module, or tailwindcss is never imported through the PostCSS plugin, the class is unknown. Add @reference to the module, or fix the @import and postcss.config.mjs.
Fix it fast
1Find out which cause you have
Find which file holds the failing @apply line. The build error names it. Then check whether that file is a CSS module or your main global stylesheet.
grep -rn "@apply" --include="*.css" . --exclude-dir=node_modules --exclude-dir=.next2Match what you see, then jump to its fix
- 1
The error points at a *.module.css file, while classes in the main globals.css work fine.@apply is used inside a CSS module or a separate stylesheetFix - 2
Utilities fail everywhere, including in the global stylesheet, and the project was upgraded from an older Tailwind setup.Tailwind is not imported or the PostCSS plugin is not wired upFix
- 1
What does the error look like?
Cannot apply unknown utility class
Cause 1 of 2
@apply is used inside a CSS module or a separate stylesheet
1Check
A CSS module is processed on its own. It does not see the theme, custom utilities or variants from your main stylesheet unless you point to it.
grep -rln "@apply" --include="*.module.css" . --exclude-dir=node_modules --exclude-dir=.next2Fix
Put @reference at the top of the module. It imports your main stylesheet for reference only, so no CSS is duplicated in the output. With the default theme and no customizations you can reference tailwindcss itself.
/* app/blog/blog.module.css */
@reference "../globals.css";
.title {
@apply text-2xl font-bold;
}3Verify
Run the production build; the unknown-utility error for that file should be gone.
npm run buildConfirmed by tailwindcss.com
Cause 2 of 2
Tailwind is not imported or the PostCSS plugin is not wired up
1Check
Tailwind 4 on Next.js needs the @tailwindcss/postcss plugin and a single @import of tailwindcss in the global CSS file. Check both files and that the CSS file is imported once (from your root layout in the App Router).
cat postcss.config.mjs
grep -rn "tailwindcss" --include="*.css" . --exclude-dir=node_modules --exclude-dir=.next2Fix
Install the packages, register the plugin and import Tailwind at the top of the global stylesheet.
npm install tailwindcss @tailwindcss/postcss postcss
// postcss.config.mjs
export default {
plugins: {
"@tailwindcss/postcss": {},
},
};
/* globals.css */
@import "tailwindcss";3Verify
Restart the dev server and use a utility such as text-3xl on a page.
npm run devConfirmed by nextjs.org
How do I stop it coming back?
- Treat every new CSS module that uses @apply as needing an @reference line.
- Prefer utility classes in markup over @apply, as the Next.js docs recommend Tailwind for most styling.
- Keep one global stylesheet that imports tailwindcss, imported from the root layout.
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 fixWeb 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 fixWeb apps
Apollo Server rejects a request as a potential CSRF
HTTP 400 Bad Request from the GraphQL endpoint
Apollo Server's CSRF prevention is on by default.
3 causes, each with a fixWeb apps
Clerk cannot read its publishable key in a Next.js app
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY is undefined
Clerk reads NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY.
3 causes, each with a fixWeb apps
The shell cannot find create-next-app
command not found: create-next-app
create-next-app is not meant to be installed as a shell command.
2 causes, each with a fixWeb apps
ESLint fails with: Cannot find module 'next/babel'
ESLint stops on the first file with a Babel or parser error instead of listing lint results
next/babel is a Babel preset that ships inside the next package.
3 causes, each with a fix