Maaz Zindani

Loading the index…

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

Tailwind v4 says border-border does not exist

ErrorCannot apply unknown utility class `border-border`

Short answer

Tailwind v4 builds a utility only when a matching theme variable exists. For border-border you need --color-border inside @theme, and @theme inline when it points at another CSS variable. Stylesheets bundled separately, such as CSS modules, also need an @reference line before @apply can see your theme.

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

Fix it fast

  1. 1Find out which cause you have

    Check whether a --color-border variable is defined in a @theme block anywhere in your CSS.

    grep -rn "color-border\|@theme" app src --include=*.css
  2. 2Match what you see, then jump to its fix

    1. 1Error comes from a global CSS file using @apply border-borderNo --color-border theme variable existsFix
    2. 2border-border exists but resolves to the wrong or no colourThe theme variable points at another variable and needs inlineFix
    3. 3The error appears in a CSS module or a style block, not in the main CSS file@apply runs in a separately bundled stylesheetFix

What does the error look like?

  • Cannot apply unknown utility class `border-border`

Cause 1 of 3

No --color-border theme variable exists

1Check

Theme variables defined with @theme decide which utility classes exist. A name inside the color namespace becomes a utility with the same name.

grep -rn "@apply" app src --include=*.css

2Fix

Define the variable in @theme.

@import "tailwindcss";

@theme {
  --color-border: oklch(0.9 0 0);
}

3Verify

Restart the dev server and reload the page.

npm run dev

Confirmed by tailwindcss.com

Did this fix it?

Cause 2 of 3

The theme variable points at another variable and needs inline

1Check

When a theme variable references another variable, Tailwind's docs say to use the inline option, otherwise utilities can resolve to unexpected values.

grep -rn "var(--border)" app src --include=*.css

2Fix

Declare the raw value in :root and map it with @theme inline, the pattern shadcn/ui uses for Tailwind v4.

:root {
  --border: oklch(0.922 0 0);
}

@theme inline {
  --color-border: var(--border);
}

3Verify

Use the class in markup and inspect the computed border colour.

# Browser devtools: Computed, border-color

Confirmed by tailwindcss.com

Did this fix it?

Cause 3 of 3

@apply runs in a separately bundled stylesheet

1Check

In v4, stylesheets bundled separately (CSS modules, Vue, Svelte or Astro style blocks) cannot see theme variables or custom utilities from other files.

grep -rln "@apply" . --include=*.module.css

2Fix

Import the main stylesheet as a reference at the top of that file.

@reference "../app/globals.css";

.card {
  @apply border border-border;
}

3Verify

Rebuild; the unknown utility error is gone.

npm run build

Confirmed by tailwindcss.com

Did this fix it?

How do I stop it coming back?

  • Keep all theme variables in one main CSS file imported with @import "tailwindcss".
  • Add @reference to every CSS module that uses @apply.
  • Use @theme inline whenever a theme value is var(...) of another variable.
  • Remember v4 changed the default border colour to currentColor; set colours explicitly.

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

Hydration failed after adding next-themes dark mode

Console reports a server and client mismatch on the html element

next-themes changes the html element and knows the theme only in the browser, so server HTML and client HTML differ.

3 causes, each with a fix

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.