Tailwind build says the dark: class does not exist
The `dark:` class does not exist. If `dark:` is a custom class, make sure it is defined within a `@layer` directive.Short answer
The build error means the CSS file being compiled cannot see your dark variant. On Tailwind v4 the usual reasons are: the file is bundled separately, such as a CSS module, and needs @reference; the dark variant is defined in a v3 config file that v4 no longer loads; or a custom class sits in @layer instead of @utility.
Fix it fast
1Find out which cause you have
Find out which Tailwind major version is installed, then find the stylesheet named in the build error.
npm ls tailwindcss; grep -rn "@apply" app styles components --include=*.css2Match what you see, then jump to its fix
- 1
The error points at a CSS module or another separate .css file that uses @applyThe stylesheet is bundled apart from your main CSS fileFix - 2
The project has a tailwind.config.js with darkMode: 'class', and the CSS starts with @import "tailwindcss"darkMode was set in tailwind.config.js, which v4 does not load by itselfFix - 3
The error names your own class and the CSS defines it inside @layer utilities or @layer componentsA custom class is declared in @layer, which v4 no longer treats as utilitiesFix
- 1
What does the error look like?
The `dark:` class does not exist. If `dark:` is a custom class, make sure it is defined within a `@layer` directive.dark: utilities work in markup but the build fails where @apply uses them in a separate CSS file
Cause 1 of 3
The stylesheet is bundled apart from your main CSS file
1Check
In v4, stylesheets bundled separately, such as CSS module files, do not see the theme variables, custom utilities and custom variants defined in other files.
grep -rln "@apply" . --include=*.module.css --exclude-dir=node_modules2Fix
Import the main stylesheet with @reference at the top of that file, so the definitions are available without copying CSS into the bundle. Or skip @apply and use theme variables.
/* components/card.module.css */
@reference "../app/globals.css";
.card {
@apply bg-white dark:bg-zinc-900;
}3Verify
Run the build again.
npm run buildConfirmed by tailwindcss.com
Cause 2 of 3
darkMode was set in tailwind.config.js, which v4 does not load by itself
1Check
JavaScript config files are no longer detected automatically in v4. In v4, class-based dark mode is defined in CSS by overriding the dark variant.
ls tailwind.config.*; grep -n "@import\|@config\|@custom-variant" app/globals.css2Fix
Define the variant in your main CSS file. If you still need the old config file for other options, load it with @config.
/* app/globals.css */
@import "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));
/* only if you keep a JS config */
@config "../tailwind.config.js";3Verify
Put class="dark" on the html element and check that dark: utilities apply.
npm run devConfirmed by tailwindcss.com
Cause 3 of 3
A custom class is declared in @layer, which v4 no longer treats as utilities
1Check
In v3, classes inside @layer utilities and @layer components became real utilities that worked with variants. In v4 the @layer at-rule is native, so Tailwind does not pick them up.
grep -rn "@layer utilities\|@layer components" app styles --include=*.css2Fix
Declare the class with @utility so it can be used with @apply and variants.
@utility tab-4 {
tab-size: 4;
}3Verify
Run the build again.
npm run buildConfirmed by tailwindcss.com
How do I stop it coming back?
- Keep one main CSS file that imports Tailwind, and @reference it from every separate stylesheet that uses @apply.
- Prefer utility classes in markup over @apply in CSS modules.
- Read the v4 upgrade guide before moving a project from v3.
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 CSS 4 build fails on @apply in a Next.js project
Cannot apply unknown utility class
Tailwind 4 only knows its utilities in a stylesheet that imports Tailwind.
2 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