Tailwind v4 says border-border does not exist
Cannot 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.
Fix it fast
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=*.css2Match what you see, then jump to its fix
- 1
Error comes from a global CSS file using @apply border-borderNo --color-border theme variable existsFix - 2
border-border exists but resolves to the wrong or no colourThe theme variable points at another variable and needs inlineFix - 3
The error appears in a CSS module or a style block, not in the main CSS file@apply runs in a separately bundled stylesheetFix
- 1
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=*.css2Fix
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 devConfirmed by tailwindcss.com
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=*.css2Fix
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-colorConfirmed by tailwindcss.com
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.css2Fix
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 buildConfirmed by tailwindcss.com
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
Tailwind classes have no effect in a Next.js app
Styles from Tailwind never reach the page after install
The page loads but Tailwind classes do nothing when the generated CSS never reaches the page.
5 causes, each with a fixWeb apps
There is no tailwind.config.js after installing Tailwind 4 and HeroUI in Next.js
HeroUI components render unstyled
Nothing is broken: Tailwind CSS 4 is configured in CSS and no longer creates tailwind.config.js.
3 causes, each with a fixWeb 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 fixWeb 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
A shadcn/ui Dialog stays open after the form is submitted
Form submits and the data saves, but the modal remains on screen
A shadcn Dialog is a Radix dialog.
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 fix