Maaz Zindani

Loading the index…

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

Tailwind build says the dark: class does not exist

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

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

Fix it fast

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

    1. 1The error points at a CSS module or another separate .css file that uses @applyThe stylesheet is bundled apart from your main CSS fileFix
    2. 2The 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. 3The 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

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_modules

2Fix

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 build

Confirmed by tailwindcss.com

Did this fix it?

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

2Fix

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 dev

Confirmed by tailwindcss.com

Did this fix it?

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=*.css

2Fix

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 build

Confirmed by tailwindcss.com

Did this fix it?

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 fix

Next step

Want this handled for good?

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