Maaz Zindani

Loading the index…

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

Tailwind CSS 4 build fails on @apply in a Next.js project

ErrorCannot apply unknown utility class

Short 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.

  • Applies to Next.js 15, Tailwind CSS 4, @tailwindcss/postcss 4, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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=.next
  2. 2Match what you see, then jump to its fix

    1. 1The 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. 2Utilities 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

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=.next

2Fix

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 build

Confirmed by tailwindcss.com

Did this fix it?

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=.next

2Fix

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 dev

Confirmed by nextjs.org

Did this fix it?

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 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.